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A TRUE SPREADSHEET 
CONTROL! 


(THIS IS NOT A GRID!) 


Drover’s Professional 
ToolBox for Windows 

With 23 custom controls, including Far- 
Point’s industry unique full-featured 
spreadsheet control (not a grid!), For¬ 
matted Edit Controls, Tool Bar and 
Status Bar, ability to add 3D effects to 
dialog boxes, View Pictures with anima¬ 
tion, and Enhanced Listbox this package 
is a developer’s dream come true. 

Over 300 (unctions are built in, including 
DOS System functions, Date/Time sup¬ 
port, String functions, and Enhanced file 
support. 

Drover’s Professional Toolbox supports 
MSC 7.0, Borland C + +, Turbo Pascal, 
Actor, WindowsMaker Pro, Borland 
Resource Workshop and Dialog Editor. 

Drover’s Professional Toolbox for Win¬ 
dows is only $345.00. There are no 
royalties and of course you receive our 
30 day no-hassle, money-back guar¬ 
antee. 


DON'T CHEAT YOUR END 
USER WITH A GRID WHEN 
YOU COULD BE GIVING THEM 
A TRUE SPREADSHEET 
CONTROL. 

FarPoint’s Spreadsheet control is unparalleled 
by any other package in its features, flexibility 
and power. The spreadsheet may be optionally 
locked so the user cannot make any changes. 
The width and height of columns and rows may 
be changed by the programmer or by the user. 
The font, color, and data type may be changed 
for any row, column or cell. Cells can have the 
following data types: edit, date, time, integer, 
float, static, formatted pic, combo box, button, 
and picture. Formulas can be added to any cell. 
Editing is performed within the cell. 

CALL OR FAX FARPOINT TODAY: 

( 614 ) 7654333 

Fax: (614) 765-4939 


Visual Architect 

for Visual Basic 

“Visual Architect™ is a product 
that no serious Visual Basic devel¬ 
oper can do without.” 

Along with the industry’s 
most powerful and flexible 
true Spreadsheet custom 
control (not a grid!), Visual 
Architect™ features Date 
with Calendar, Time, Float, 

Integer, Formatted PIC and 
View Text controls. 
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The Visual Architect™ 
manual is professionally writ¬ 
ten and contains extensive 
documentation. 

Visual Architect™ is only $245.00. 
There are no royalities and of course you 
receive our 30 day, no-hassle, money- 
back guarantee. 
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To Order VMData 
or to receive a free report 
entitled 

“Data Management 
Solutions for Windows C 
and C++ Programmers” 

Call toll-free 

( 800 ) 826-8086 

or fax your request to 

( 713 ) 460-2651 


Here's the problem: _ 

Windows doesn’t offer virtual memory for data in all modes. With 
the 8192 system-wide GlobalAlloc limit and the inability of Windows 
to swap data to disk in some modes, programs using as little as 100K 
of dynamic data may fail to execute properly in some Windows 
environments. 


J li J V VMData is the solution. Designed to be used for 
high-performance, commercial-quality applications, VMData is a 
Windows DLL that manages up to 128 megabytes of data. VMData’s 
advanced virtual memory scheme adheres to Windows rules and 
recommendations, and uses all memory types available in all 
Windows modes. This ensures that your application is a “good 
citizen” under Windows 
and will not impede the 
overall performance of 
the end-user’s machine. 


POCKET 


VMData supports Microsoft®C 
and C++ (5.1,6.0,7.0), Borland® C++ 
(2.0,3.0,3.1) across multiple platforms. 


No Limits 


PO Box 821049 Houston, TX 77282 Phone (713) 460-5600 Fax (713) 460-2651 

“Pocket Soft” and "VMData” are trademarks of Pocket Soft, Inc. All other trademarks are property of respective owners. 
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C CODE FOR THE PC 

source code, of course 

Embedded DOS (full-features, real-time, multitasking, 3.31-compatible DOS for embedded system and self-bootable installations).$375 

Style (a C+ + class library to build, maintain and traverse arbitrary, non-taxonomic links between C+ + objects).$300 

Spell Time (spelling checker for incorporation into text products; no royalty; large dictionary; small and fast).$300 

ZIP Image Processor & Victor Image Library Version 2.2 (brightness, contrast, merge images, TIFF/GIF/PCX/bin, HP ScanJet support) . . $290 

NE W! INGRAF (graphics for scientists & engineers, all sorts of graphs & plots; specify Microsoft or Borland).$275 

The Snooper (Ethernet protocol analyser for Novell Net mre and LAN Manager Networks; capture packets; real-time display).$275 

'HirboTEX (Release 3.0; HP, PS, dot drivers; CM fonts; LalgX; MetaFont).$250 

Rogue Wave tools.h++ or math.h++ Class Library (extensive docs).each $240 

InControl 1bolbox(fonns package for Windows; validation functions, date/time, regular expression formatted text control).$210 

PxSQL (SQL for Borland's Paradox Engine; ANSI X3.135-1989 SQL-DML standard; network server not required).$180 

C-pslib (PostScript generation library for C programs; includes complete graphics, font, rotation & paragraph support).$170 

C/C+ + Libraries by Code Farms (persistent C structures, ER models, dynamic arrays, disk pager, database functions, much more).$170 

Viewpoint (C++ graphics library, 32-bit color, pattern fill, scroll & bitmap, coordinate tranformations)...$170 

NEW! XASM (cross assemblers) .$150 

Minix Operating System (Version 1.5; Unix-like operating system, indudes manual; spedfy 5.25” or 3.5” diskettes).$150 

ViewTHeve (relational view of Novell Btrieve databases; mdudes EZTHeve).$150 

Delorie GCC for MS-DOS (Version 1.05; indudes C++, assembler, DOS extender, 387 emulation; complete source code and makefiles) . . $150 

Booter Tbolkit (floppy disk bootstrap routines, DOS file system, light-weight multitasking, windows, fast memory management) .$120 

Dr. MD (runtime memory analyzer & debugger; find many memory corruption errors; examine memory usage).$110 

NEW! 386BSD Version 0.1 & LINUX Version 0.96(two Unix clones for Intel 386).$100 

PC/IP (CMU/MIT TCP/IP for PCs; Crynwr drivers, NFS server, Bdale mailer, PCRoute/PCBridge, NDIS/ODI drivers, Beholder, more) . . . $100 

Demacs (complete GNU Emacs for DOS; needs djgcc to build; based on 18.55).$100 

Script Interpreter (a oommand script interpreter for DOS-based systems; C-like script language; lots of features).$90 

NE W! NETS Version 3.0 (neural net simulator from COSMIC) .$85 

NE W! Ibrow (programmer’s Windows-based editor; large files, help, undo/redo, drag-n-drop, function & type tags).$85 

HorC+ + (C+ + Class Library for Borland's Paradox Engine).$80 

CPPCOMM (Version 2.0; C++class library for serial communications).$75 

FlexList (doubly-linked lists of arbitrary data with multiple access methods; specify C or C-|—|-).$65 

LDB (Loose Data Binder; persistent data objects for C++; handles pointers between objects) .$60 

Kier DateLib (all kinds of date manipulation; translation, validation, formatting, & arithmetic).$60 

Coder's Prolog (Version 3.0; inference engine for use with C programs).$60 

NEW! PCCTS (Purdue Compiler Construction Tool Set; ported to Microsoft Q like YACC and LEX together with lots of additional features) . . . $60 

MEM-WING (global memory manager for Windows, supports standard C memory allocation calls to "wing” your old C code into Windows) . $55 

BigFloat (arbitrary precision floating point arithmetic and functions; includes BCD conversion).$50 

CALC (ASCII algebraic expression evaluator, unlimited parenthesis nesting, symbols, 32 built-in functions, easily extended).$50 

Backup & Restore Utility by Blake McBride (multiple volumes, file compression & encryption).$50 

Floppy TAR (TAR backup and restore on MS-DOS devices; direct access to non-standard devices) .$50 

SuperGrep (exceptionally fast, revolutionary text searching algorithm; also searches sub-directories).$50 

OBJASM (convert .obi files to .asm files; output is MASM compatible).$50 

CLIPS Version 5.1 (rule-based expert system generator; advanced manuals available at additional cost).$50 

NIH Class Library & Book (basic C++ classes & Data Abstraction and Object-Oriented Programming m C+ + in softback by Keith Gorlen) . $50 

Editor Pack (19 public domain editors; including microEmacs 3.11, Stevie, Elvis, Moke, mg2a, DTE, Jove, Origami, & GRIEF) .$50 

MicroC C Compiler (retargetable C compiler/optimizer, lots of docs, very portable, 8086 tables included; tables for 7 extra epu’s $50) .... $50 

PICTOR (I/O library; windows, hypertext, text compression, serial comm, printer support, break handling; text editor example).$45 

TOUR (beautiful traveling salesman problem solver, finds minimum length paths quickly, includes graphics & plotting programs) .$40 

DES Encryption & Decryption (2500 bits/second on 4.77 MHz PC for on-the-fly encryption at 2400 baud; domestic distribution only) .... $40 

NEW! COPS (poorman’s C++; C macro package which implements C++ in C).$35 

RXC & EGREP Version 2.0 (Regular Expression Compiler and Pattern Matching; finite state machine from regular expression).$35 

Database Pack (9 databases - simple to complex; isam, bplus, AVL, SDB, ID, gdbm, Requiem, Ingres89, Postgres).$35 

Bison & BYACC (YACC workalike parser generators; documentation; includes C and C+ + grammars).•.$35 

NE W! PASSWORD (password-protect a running PC while you’re away from your desk; includes intrusion log) .$30 

Spell Pack (6 spelling programs, a hyphenator, 2 utility packs and a 60K word list: Ispell, Microsp, Sp, Cspella, Spell, Dawg, Soundex) .... $30 

NE W! Alloc-GC (a garbage-collecting memory allocation library).$30 

REGX Plus (Version 2.0, search and replace string manipulation routines based on regular expressions).$30 

GNU Awk & Diff for PC (both programs in one package).$30 

Big Number Pack (7 arbitrary precision arithmetic packages in C, one in Fortran but free Fortran-to-C converter is included) .$30 

Crunch Pack (30 file compression & expansion programs; now includes portable ZIP).$30 

UUPC Pack (UUCP for the PQ UUPC Version 1.11Q by Wonderworks and smail/PC Version 2.5 by Stephen G Trier).$25 

PERL for MS-DOS (Version 4.019; C, sed, awk, and shell all rolled into one language; includes hardcopy docs).$25 

Tel Version 6.1 (Tbol Command Language; add shell programming capability to any command line; elegant command line language) .... $25 

FLEX (fast lexical analyzer generator; new, improved LEX; BSD Version 2.3.6 with docs).$25 

GNU RCS (FSFs version of the Revision Control System; like Unix’s SCCS only better; keeps track of software development).$20 

PCAL Personal Calendar (generates PostScript calendar for any month or year, lots of options, personalization file foryour dates & schedule) $20 

Publisher’s Interchange Language (PIL Tool fat, Version 5.0, API Z0 by Quark) .$20 

NetCDF (Network Common Data Form; general-purpose data exchange for scientific data; many tools and programs available).$20 

NE W! CPP Pack (3 K&R C preprocessors).$20 

Data 

Moby Thesaurus (25K root words, 1.2M synonyms).$350 

Moby Part-of-Speech (200,000 words and phrases described by prioritized part(s)-of-speech).$120 

Moby Words (500,000 words & phrases, 9,000 stars, 15,000 names).$80 

Moby Shakespeare (plays, sonnets, etc. ... every last word).$60 

Dictionary Word List (234,932 words in alphabetical order).$60 

Roget’s 1911 Thesaurus.$40 

U. S. Cities (names & longitude/latitude of 3Z000 U.S. cities and 6,000 state boundary points).$35 

CIA World Bank II Database (13MB of maps, 5.7M vectors; coastlines, rivers, political boundaries; Africa, Asia, Europe, N. & S. America) . $35 

The World Digitized (100,000 longitude/latitude of world country boundaries).$30 

Lots ’O Words (160,086 German, 178,430 Dutch, 61,843 Norwegian, 60,453 Italian, 138,257 French, 53,142 English).$30 

Text Pack (1990 CIA World Fact Book, Hacker’s Jargon File, Acronyma, Koran, Mormon Scriptures, One Liners, Mnemonics, more) .... $25 

CD-ROMs 

FontMaster Library (soft fonts for HP and HP compatible laser printers, 36 different type faces; 5,200 bit mapped fonts; 300MB).$70 

Updated! InfoMagic (X11R5, Tahoe 4.3, complete GNU, ISODE, KA9Q & NCSA TCP/IP, Demaos, Djgcc, 386bsd, some GNU on Windows NT) . . . $70 

Prime Time Freeware (over 1 gigabyte of Unix C code).$60 

NE W! Walnut Creek Desktop Library River 1,000 texts: Aesop, Shakespeare, Dickens, Doyle, Melville, dictionaries, word lists, thesaruses, etc.) . . $35 

V&lnut Creek X11R5 and GNU (X11R5 with contributed and comp.sourcesjc, 120 GNU programs, SPARC executables).$35 

W&lnut Creek Usenet and Simtel Unix-C (600MB).$35 

W&lnut Creek Simtel 20 MSDOS Archive (C source code but lots of other stuff too).$20 


11100 Leafwood Lane much more ... ask for catalog FAX: (512) 258-1342 

Austin, Texas 78750-3587 USA E-mail: info@acw.com 

Free surface shipping for cash in advance For delivery in Texas add 7% MasterCard/VISA 
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From 

the Editor 


Due to reader requests, we have been working on a plan to distribute the code 
listings that appear in the magazine. I am happy to say that we now have a fairly 
wide distribution system in place — encompassing BBS’s, CompuServe, the Internet, 
and WIX —all places where programmers gather to ask and answer questions about 
DOS and Windows programming. 

The list of systems where you can obtain code listings is shown below. If you get 
your code from one of these sources, please take some time to look around and see 
what else they have to offer. Our thanks to the hard-working operators who run 
these BBS’s and make them a great source of technical information. Thanks also to: 
Larry O’Brien of Computer Language, who was kind enough to give us space in the 
Computer Language forum on CompuServe-, to Jim Kyle for invaluable help with the 
mechanics of the CompuServe forum; and to Tony Lockwood for handling the 
mechanics of BlX/WIX. 

As part of our ongoing effort to increase the value of the magazine, we are also 
working on making the code in the magazine less vendor-dependent. In this issue, 
you will see that some of the articles are marked with a logo that indicates which 
compilers they have been compiled with. We are starting small, but our goal is to 
remove as many dependencies on specific vendors' compilers and on operating sys¬ 
tem versions as possible. Please keep sending us your criticisms and compliments as 
we continue to improve our services. 


Bulletin Board Systems 

Phoenix Chapter ACM Library 

(602) 970-0474 

The Programmer's Corner 

(301) 596-7692 or (410) 995-6873 

The Courts of Chaos 

(501) 985-0059 

EmmaSoft Shareware Board 

(607) 533-7072 

Cornerstone 

(206) 362-4283 

Other Systems 

CompuServe 

GO CLMFORUM, section 7 

BIX/WIX 

join listings, change areas to "win.dos.dev” 

uunet 

"/published/windowsdos/19YY/monYY.zip 

Accessible via anonymous FTP from ftp.uu.net or 
via uucp from (900) GOT-SRCS (login name “uccp", 
no password, $.50 per minute). 


Ron Burk 

Editor 

CIS: 70302,2566 ; BIX: rlburk-, Internet: ronb@rdpub.com (“... !uunet!rdpub!ronb") 
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Custom Software Services 


IBM produces 
a great new line 
of software. 


Yours. 


You’ve just developed a terrific new software 
program. Who do you trust to get it to your 
customers quickly, efficiently and accurately? 
Come to IBM. 

We have over 30 years of experience and 
a worldwide distribution network. Our facilities 
extend across five continents, which puts us close 
to your markets, so we can provide prompt, cost- 
effective delivery. 

At IBM you’ll deal with a single supplier. 

Our full range of services includes everything 
from replication and publication, to packaging and 
delivery. We handle all media, including diskettes, 
tape and CD-ROM. Our stringent quality control 
procedures ensure accuracy and security. Plus, we 
can give you a competitive edge by custom-tailor- 
ing your software to meet your customers’ needs. 

IBM can also help you save money. We can 
put our people, equipment and expertise to 
work for you to help reduce your overall costs. 

Talk to our manufacturing and distribution 
experts today. And count on us to treat your 
software like it was our own. 

Call IBM at 1800 926-0364. 


• Deal with a single supplier with a full range 
of services. 

■ Reach markets quickly through the IBM 
worldwide distribution network. 

• Reduce overall costs with IBM in-place capabilities. 


IBM is a registered trademark ol international Business Machines Corporation. 
© 1992 IBM Corporation. 



















Networks 



Plug into TCP/IP 
with Windows Sockets 

Victor R. Volkman 


Introduction 

Although Microsoft Windows 3.1 can take advantage of most of the available 
network services, writing your own network-independent client/server applications 
can be a daunting task. There are many competing network programming interfaces, 
but each is limited in its coverage of platforms and networks. Today, most vertical 
applications demand connectivity between PCs and UNIX-compatible workstations 
such as Sun Sparc, IBM RS/6000, and DEC Ultrix. Even though some network APIs can 
connect both PCs and UNIX workstations, the Windows Sockets API is the only 
emerging vendor-independent choice. Before covering Windows Sockets in depth, I'll 
first look some of the competing APIs. 

Network APIs for Windows 

The diversity of standards for network programming under Windows simply mir¬ 
rors the situation on the basic MS-DOS platform, where the lack of an industry stand¬ 
ard has spawned a large variety of solutions. The current top contenders for Win¬ 
dows 3.1 network programming include NetBIOS, WNet, vendor-specific APIs, and 
Windows Sockets. Each has barriers that may prevent it from becoming a complete 
solution. 

The venerable NetBIOS API, first introduced by IBM in 1984, has become the de 
facto standard for DOS client/server applications. Every DOS Network Operating Sys¬ 
tem (NOS) has an installable NetBIOS driver. However, NetBIOS has been slow to enter 
the UNIX world and has not yet achieved acceptance on UNIX workstations running 
TCP/IP (Comer 1991). Additionally, even industry experts consider NetBIOS under Win¬ 
dows to be a complex and difficult environment (Baker 1992). However, Win32 API 
and Windows NT are expected to alleviate much of the extra complexity. 

The WNet API is formally documented in the Microsoft Windows 3.1 Device Driver 
Kit (DDK). These functions are basically entry points into the vendor-supplied network 
drivers for Windows. WNet includes higher-level functions than either Windows 
Sockets or NetBIOS. For example, WNet maps network filesystems to local drives and 
submits print jobs. However, the current implementation fails to provide sufficient 
client/server communication calls. Even with client/server calls, applications would 
still not be portable to DOS-only or UNIX workstations. 


Victor R. Volkman received a BS in Computer Science from Michigan Technological 
University. He is a contributing editor for Windows/DOS Developer's Journal. He is 
currently employed as Software Engineer at Cimage Corporation of Ann Arbor, 
Michigan. He can be reached directly at the HAL 9000 BBS (313) 663-4173 or as 
vrv@cimage.com on Usenet. 
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Also, the vendors who have traditionally offered toolkits for 
DOS networks are releasing special versions tailored for Win¬ 
dows programming. The Sun PC-NFS Programmer's Toolkit v4.0, 
Lantastic Programmer’s Interface, and the Novell Netware C In¬ 
terface for Windows are just a few examples. Some of these 
offer the same API under DOS and Windows, but others do 
not. Although many of the toolkits allow DOS/UNIX connec¬ 
tivity, each naturally requires its own proprietary NOS drivers 
on the PC. This means that applications developed to run with 
one vendor's toolkit may not work on a PC running another 
vendor's NOS. 

The Windows Sockets specification grew out of an informal 
session held at the October 1991 interop convention in San 
Francisco. The basic idea was to build the established 
knowledge and experience with UNIX-based client/server solu¬ 
tions into a DLL suitable for MS Windows. The Windows Sock¬ 
ets API (or WSA) specification has been developed and 
reviewed by a committee representing many networking ven¬ 
dors and Microsoft Corporation. The Windows Sockets commit¬ 
tee released version 1.0 of the specification in Spring 1992 and 
expects to release version 1.1 of the specification following the 
October 1992 Interop convention. 

Since Windows Sockets emulates the Berkeley Software 
Distribution (BSD) UNIX implementation, it already has 
widespread connectivity on the UNIX platform. It is also the 
only network API allowing any degree of source portability 
between Windows and UNIX. Windows Sockets will be avail¬ 
able on many TCP/IP networks in late 1992. In the remainder 
of the article, I'll discuss socket fundamentals, the socket API, 
Windows Sockets source portability, and Windows Sockets ex¬ 
tensions. 

Socket Fundamentals 

In 1982, the 4.1CBSD UNIX release for the DEC VAX-11 offi¬ 
cially introduced sockets to the world. BSD sockets emulate 
file descriptors as an extension of the UNIX file I/O system. 
Accordingly, you can call the standard library functions, such 
as read() and write(), to receive and transmit data. Since 
network programming requires more control than the file 
descriptor functions alone can provide, several new functions 
were added. For example, establishing a connection requires 
details about hosts, ports, protocols, and other options that 
simply cannot be expressed by open() alone. 

A socket represents only one endpoint of a connection. 
Thus, two sockets are needed to complete the path. Concep¬ 
tually, each socket is a bidirectional pipe through which in¬ 
coming data can be received and outgoing data can be sent. 
A socket exists within the particular communication domain in 
which you created it. A domain consists of a family of com¬ 
munication protocols. For example, the 4.3BSD VAX-11 release 
included the UNIX domain (stream pipes), Internet domain 
(TCP/IP), and the Xerox Networks System (SPP and IDP). The 
UNIX domain is designed solely for processes communicating 


locally to the same host. Each domain has a distinctly different 
method of expressing the address of a communication 
endpoint Consequently, a domain is as much an address fami¬ 
ly as it is a protocol family. 

Sockets support both connection-oriented protocols and 
connectionless protocols. Connection-oriented protocols pro¬ 
vide a reliable virtual circuit, buffered transfer, and full-duplex 
connection. Connectionless protocols do not establish a reli¬ 
able virtual circuit, may be unbuffered, and are half-duplex. 
Messages sent over connectionless protocols can be lost or 
duplicated, or can arrive in the wrong order without notice. 

Sockets created for connection-oriented protocols are 
called “stream sockets.” Sockets created for connectionless 
protocols are known as "datagram sockets.” Stream sockets 
are primarily used with the Transmission Control Protocol (TCP) 
in the Internet domain and the Sequence Packet Protocol (SPP) 
in the Xerox Networks System (XNS). Datagram sockets are 
primarily used with the User Datagram Protocol (UDP) in the 
Internet domain and the Internet Datagram Protocol (IDP) in 
the XNS domain. 

Raw sockets are a special type of datagram socket mainly 
for error and routing report protocols. In the Internet domain, 
raw sockets normally use the Internet Control Message 
Protocol (ICMP) to transmit this information. Most applications 
will not need to use raw sockets. 

The Socket API 

Since the BSD socket calls have been thoroughly docu¬ 
mented elsewhere (see Bibliography), I review them only 
briefly in the next sections (I discuss the differences between 
BSD sockets and Windows sockets later in the article). Since 
the same sources also cover the fundamentals of TCP/IP net¬ 
working protocols, I assume basic familiarity with them. 
Figures 1 through 4 show a complete list of socket calls and 
their representation under BSD UNIX and Windows. Because 
the BSD UNIX implementation treats sockets as ordinary I/O, 
the boundaries of the socket API can appear fuzzy to the 
uninitiated. 


How to Get the Windows 
Sockets Interface 

The Windows Sockets interface consists of UIN- 
S0CK.DLL, MINSOCK.H, and other support files. Contact 
your PC network operating system vendor for current 
availability information. Vendors such as FTP Software 
(PC/TCP), Sun Microsystems (PC-NFS), Beame & Whiteside 
(BW-NFS), NetManage (NEWT-SDK), GENISYS Comm 
(GCP++), and Distinct (TCP/IP for Windows SDK) have an¬ 
nounced implementation plans. □ 
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Every application, whether client or server, must first create a 
socket by calling socket(). The socket() call expects parameters 
for address family, socket type, and protocol. A sample invoca¬ 
tion might appear as follows: (continued on p. 10) 


Figure 1 Socket Functions in BSD and Windows 
Sockets 

Function Name 

4.3BSD UNIX 

Windows Sockets 

acceptO 

Yes 

Yes 

bindO 

Yes 

Yes 

closeO 

Yes 

No 

closeO is replaced by 
c/osesocketO in WSA. 

dosesocketO 

Yes 

Yes 

connectO 

Yes 

Yes 

fnctIO 

Yes 

No 

fnctIO and ioctlO are 
replaced by 
ioctlsocketo in WSA. 

getpeernameO 

Yes 

Yes 

getsocknameO 

Yes 

Yes 

getsockoptO 

Yes 

Yes 

htonlo 

Yes 

Yes 

htonsO 

Yes 

Yes 

inet addrO 

Yes 

Yes 

inetJnaofO 

Yes 

No 

inet makeaddrO 

Yes 

No 

inet netofo 

Yes 

No 

inet networkO 

Yes 

No 

inet notaO 

Yes 

Yes 

ioctlO 

Yes 

No 

fnctIO and ioctlO ore 
replaced by 
ioctlsocketo in WSA. 

ioctlsocketo 

No 

Yes 

listenO 

Yes 

Yes 

ntohIO 

Yes 

Yes 

ntohsO 

Yes 

Yes 

reado 

Yes 

No 

read() and writeO 
are replaced with 
rccvO and sendO in 
WSA. 

recvO 

Yes 

Yes 

recvfromO 

Yes 

Yes 

recvmsgo 

Yes 

No 

selecto 

Yes 

Yes 

sendO 

Yes 

Yes 

sendmsgO 

Yes 

No 

sendtoO 

Yes 

Yes 

setsockopto 

Yes 

Yes 

shutdownO 

Yes 

Yes 

socket!) 

Yes 

Yes 

socketpairO 

Yes 

No 

writeO 

Yes 

No 

reado and writeO 
are replaced with 
rccv() and sendO in 
WSA. 
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Figure 2 Database functions in BSD and Windows 
Sockets 

Function Name 

4.3BSD UNIX 

Windows Sockets 

endhostentO 
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No 

endnetentO 
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endprotoentO 
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endservento 
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gethostbyaddrO 
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gethostbynameO 

Yes 

Yes 

gethostentO 

Yes 

No 

gethostnameO 

Yes 

NO 

getnetbyaddrO 

Yes 

No 

getnetbynameO 

Yes 

No 

getnetento 

Yes 

No 

getprotobynameO 

Yes 

Yes 

getprotobynumberO 

Yes 

Yes 

getprotoentO 

Yes 

No 

getservbynameO 

Yes 

Yes 

getservbyportO 

Yes 

Yes 

getservento 

Yes 

No 

sethostentO 

Yes 

NO 

sethostnameO 

Yes 

No 

setnetentO 

Yes 

No 

setprotoentO 

Yes 

No 

setservento 

Yes 

No 

Note-, most applications do not require these functions. 
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sfd = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP); 

Most BSD socket implementations are expected to support at 
least UNIX (AF_UNIX ), Internet ( AF_INET ), and Xerox NS (AF_NS) 
address families. However, other address families have been 
added over the years to include IBM SNA (AF_SNA), Digital 
DECnet (ftF_DECnet ), and Apple AppleTalk (fiF_APPLETALK) 
among others. As mentioned earlier, the socket types must 
include at least stream ( SOCK_STREAM ), datagram 
(SOCK_DA TAG RAH), and raw ( SOCK_RAU) types. Xerox NS net¬ 
works should have SPP sockets too ( SOCK_SPP ). Most often, the 
socket() protocol parameter is set to zero and the socket 
library picks the protocol based on the address family and 
socket type. However, raw socket applications normally ex¬ 
plicitly name the protocol. 

Since sockets are file descriptors, they can be terminated 
with the ordinary close() call. The system still attempts to 
finish transmitting any pending data that might be left. 

Stream Sockets 

The steps to be taken after you have opened a socket 
depend largely on whether you are using a connection- 
oriented protocol (e.g., TCP) or a connectionless protocol (e.g., 
UDP). In a connection-oriented protocol, a server application 
must issue calls to bind(), listenf), and accept() before it 
can actually receive data from a client By contrast, clients in a 
connection-oriented protocol need only issue connect () 
before sending data to a server. 

For the server, the bind() call associates the socket with a 
sockaddr network address structure. The sockaddr structure 
contains only an address family constant (AF_*) and 14 bytes 
of domain-specific data. In actuality, you must pass a domain- 
specific structure and simply cast it to a sockaddr pointer. For 
example, an Internet domain server might use: 

srv_addr.sin_family = AF_INET; 
srv_addr.sin_addr.s_addr = htonl(INADDR_ANY); 
srv_addr.sin_port = htons(MY_PORT); 
err = bind(sfd, (struct sockaddr *) &srv_addr, 
sizeof(srv_addr)); 

For hosts with more than one network address (multihomed), 
the constant INDADRR_ANY allows the server to receive data 
on any network address. The htonl () and htons() functions 
ensure that data is correctly byte-ordered for the host on 
which it is running. The constant MY_PORT represents a well- 
known port number. 

Next, the server calls listen() to designate the bound 
socket as ready to receive incoming connect () requests. The 
listen() function also specifies the maximum allowable 
number of backlogged pending connect () requests. For his¬ 
torical reasons, this value is normally 5: 

err = listen(sfd, 5); 

The server's first call to accept () usually follows immediately 
upon the invocation of listen(). The accept() function nor¬ 
mally blocks the server process until an incoming request 
arrives. It then returns a new socket for communicating with 


Page 10 - Windows/DOS Developer’s Journal 


December 1992 










































Get The Big Picture. 
One Piece At A Time 


Graphical User 
Interface Design 

Software Quality 
Assurance 


People & 
Productivity 


Charles Petzold 


Cross Platform 
Development 


Tim Lister 


PenBased 

Environments 


Andrew 

Schulman 



Programming 
in C++ 

Using Application 
Frameworks & Visual 
Programming Tools 


Philippe Kahn 


Methods & Tools 


Heterogeneous 

Network 

Development 


Developing For 
Windows & OS/2 


Programming 
to the API 


Object Oriented 
Programming 


Programming 

Futures 


DEVELOPME 


Debugging 


[ 199 > 3^CpNFEREN|Ce & EXHIBITION 

February 21-26,1993 - Santa Clara, California 


For those of you sifting through dozens 
of conference invitations, Software 
Development ’93 has something you 
might like: everything. 

If you want to learn how to develop 
desktop systems cleanly, quickly and cost 
effectively, or if you manage the efforts 
of others, fax us this coupon or give us a 
call. We’ll tell you how to get the big 
picture a piece at a time at SD ’93. 


YES! 


I Want More 
Info on: 

□ Attending □ Exhibiting 




Software Development'93 600 Harrison St, San Francisco, CA 94107 
Phone 415-905-2741 Fax 415-905-2222 WDDS 


Name 


Title 


Company 


Address 



December 1992 


Windows/DOS Developer’s Journal - Page 11 





















Figure 3 Domain Name Functions in BSD and 
Windows Sockets 

Function Name 

4.3 BSD UNIX 

Windows Sockets 

setdomainnameO 

Yes 

NO 

getdomainnameO 

Yes 

NO 

resjnito 

Yes 

No 

res mkqueryO 

Yes 

NO 

res sendO 

Yes 

No 

dn expandO 

Yes 

NO 

dn_compO 

Yes 

NO 


the new client, along with the client’s network address. For 
example: 


cfd = accept(sfd, 

(struct sockaddr *)&cli_addr, 
sizeof(cli_addr)); 

On the client side, the preceding connect () mirrors the ac¬ 
cept () made by the server: 

sfd = connect(cfd, 

(struct sockaddr *)&srv_addr, 
sizeof(srv_addr)); 

Once finally connected in this fashion, the client and server 
may exchange messages back and forth. Servers that allow 
multiple clients often immediately fork() a process before 
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Figure 4 Microsoft Windows-specific Extensions 

Function Name 

4.3 BSD 

UNIX 
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NO 
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NO 
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NO 
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NO 
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NO 
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NO 
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No 
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NO 
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WSAGetLastErrorO 

NO 
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No 
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NO 
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engaging in message transfer. As mentioned earlier, the stand¬ 
ard library write() and read() calls transfer data through the 
sockets on each side of the connection. Besides write(), you 
can also use send(), writevf), and sendmsgO to transmit 
data. 

The send() is equivalent to write(), but has an extra flags 
parameter. The send() flags can indicate out-of-band data 
( MSG_OOB) or routing prevention WSG_DONT_ROUTE). An out-of- 
band message bypasses the normal flow to indicate a high- 
priority condition. Handling break (Ctrl-C) messages over a 
terminal session is a common usage for out-of-band data. The 
writev() call packages up multiple message buffers for trans¬ 
mission and is thus more efficient than several sequential 
write() calls. The sendmsgO function is similar to writev(), 
but can pass access rights to the receiver as well. This is use¬ 
ful only in the UNIX domain (stream pipes). 

As you might expect, there are also several alternatives to 
the read() function: recv(), readv(), and recvmsg(). The 
primary difference between the two groups is that the recv() 
function supports only the out-of-band data ( MSG_OOB ) and 
message peek (tfSG_PEEK) flags. The MSG_PEEK flag allows data 
to be read without being dequeued. 

Datagram Sockets 

In a connectionless protocol, the client and server calls are 
a little different. The server application need only call sock¬ 
et () and bind(), eliminating the calls to listen() and ac¬ 
cept (). Further, since servers on a connectionless protocol 
really service only one client at a time, the process forking is 
usually omitted. Similarly, the clients often call bind() rather 
than connect (). The bind() call is neccessary if the client ex¬ 
pects to receive answers back from the server. 

When using bind(), the client and server typically ex¬ 
change messages with the sendtof) and recvfromf) calls. 
These functions resemble send() and recv(), except that 
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they explicitly include the network address of their counter¬ 
parts. For example, a client sends a message: 

err = sendto(fd, "Hello", 6, 0, 

&srv_addr, sizeof(srv_addr)); 

And the server receives it with: 

size = recvfrom(fd, msg, sizeof(msg), 

0, &cli_addr, &cli_len); 

Although sendtof) and recvfrom() are not strictly limited to 
datagram sockets, they are most often used for this purpose. 
The regular send() and recv() family of functions can also 
work with datagram sockets so long as you call connect () 
first. When used in a connectionless protocol, the connect () 
call does not actually initiate network traffic. 

Socket Options 

Once created, sockets can be adjusted under program con¬ 
trol to produce many different behaviors. Three functions — 
setsockopt(), fnctl (), and ioctl() — manage socket 
capabilities; the three together define more than five dozen 
options (Stevens 1990). Accordingly, I’ll highlight only a few of 
the most important options for everyday applications. 

The setsockoptf) call controls the highest level of 
capabilities for a single socket. You can enable datagram 
broadcasts ( SO_BROADCAST ), kernel debugging ( SO_DEBU6 ), and 
continuous connection monitoring (S0_KEEPALIVE). This func¬ 


tion can also control the close() behavior ( S0_LINGER) and 
force out-of-band data back in line (SOJOOBINLINE). 

The fnctl () function can operate on any open file descrip¬ 
tor, but has special semantics for sockets. Most important, it 
can enable non-blocking and asynchronous I/O signalling. The 
FNDELAY option forces the accept/), connect/), and 
read/write family of calls to return the error code 
EUOULDBLOCK instead of blocking. The FASYNC option causes 
the system to assert the SIGIO signal as soon as data is avail¬ 
able for reading. 

The ioctl() function is similar to fnctl () in that it also 
operates on an open file descriptor. The ioctl() call controls 
many aspects of files, sockets, routing, and network interfaces. 
Operations include returning the number of bytes waiting to 
be read (FIONREAD), setting the process to receive SIGIO and 
SIGURG signals ( FIOSETOUN ), testing for out-of-band data 
(SIOCATMARK), and examining the network interface 
(SIOCGIFFLAGS). 

Network Database Functions 

The network database calls report important information 
about networks, hosts, services, and protocols to your applica¬ 
tion. These functions alleviate the need for hardcoded con¬ 
stants or additional configuration file information. The actual 
information may come directly from local ASCII lookup files 
(e.g., /etc/hosts) or via an authoritative Network Information 
Service (NIS), depending on your configuration. These functions 
are often referred to as the “ GetXbyY ” functions because of 
their similar naming convention. Each of these functions 
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returns exactly one entry. For sequential access to all entries, 
there are corresponding setXentf), getXent(), and end- 
Xent() functions to open, read, and close a database. The se¬ 
quential access functions are considered obsolete — most ap¬ 
plications will not require them. 

The getnetbynamef) and getnetbyaddr() functions return 
a pointer to a netent structure. The netent structure con¬ 
tains the offical network name, list of aliases, address type, 
and network address. The gethostbynamef) and 
gethostbyoddr() functions return a pointer to a hostent 
structure describing the specified host The hostent structure 
contains the official host name, alias list, address type, and 
address list. The getservbynome() and getservbyport() func¬ 
tions return a pointer to a servent structure describing the 
specified service. The servent structure contains the official 
service name, alias list, port number, and a list of protocols. 
The getprotobynome() and getprotobynumberQ functions 
return a pointer to a protoent structure. The protoent structure 
contains the official protocol name, aliases, and protocol number. 

Windows Sockets Source Portability 

Although Windows Sockets strives for source-level por¬ 
tability with 4.3BSD UNIX sockets, the fundamental differences 
between the architectures of DOS, Windows, and UNIX make 
compromises inevitable. Specifically, source compatability may 
be inhibited by differences in the I/O function implementation, 
signal handling, domain name handling, and protocol family 
support. Since Windows Sockets has a subset of 4.3BSD 
functionality, you may encounter some limits converting UNIX 
programs to Windows. 
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I/O Differences 

The architecture of DOS and Windows limits the Windows 
Sockets implementations of UNIX I/O functions. Specifically, 
Windows Sockets does not guarantee that socket descriptors 
can be used by any of the file descriptor functions (Hall et al. 
1992: section 2.6.5.1). This means that using read(), write(), 
and close () may cause undefined effects depending on the 
Windows Sockets implementation. This limitation has been 
fixed in Windows Sockets implementations in the Windows NT 
environment 

Replacing these functions in the Windows environment 
could have been achieved by manipulating the runtime library 
files (. LIB) and redirecting the original entry points. Alternate¬ 
ly, the INI 21h functions in DOS could be chained into socket- 
aware entry points. Of course, the network drivers already 
chain INT 21h for services such as mounting logical drives 
over the network. Given these choices, it is understandable 
that Windows Sockets API providers might want to avoid 
these tricks. 

Furthermore, most PC-based compilers do not include cer¬ 
tain standard UNIX I/O functions. Specifically, the ioctl() and 
fnctl() functions remain unimplemented in Microsoft C/C++ 
7.0. Windows Sockets replaces both of these UNIX functions 
with the ioctlsocket() function. Although ioctlsocket() is 
not part of BSD UNIX, it performs some of the same tasks. For 
example, setting non-blocking I/O might appear as follows: 

err = ioctlsocket(sfd, FI0NBI0.NULL); 

The ioctlsocketf) function accepts commands to initiate 
non-blocking I/O (FI0NBI0), return the number of bytes avail¬ 
able for reading ( FIONREAD ), and test for out-of-band data 
(SI0CATMARK). For most applications, the only notable omission 
is the absence of FASYNC from fnctl() and its equivalent 
FI0ASYNC command from ioctl(). As mentioned earlier, the 
FASYNC option causes the system to assert the SIGI0 signal 
as soon as data is available for reading. 

Last, the Windows Sockets API deviates from BSD UNIX in 
that it does not set the errno variable. Since Win32 API is 
multithreaded, you would have to treat each socket call and 
errno comparison as a critical section. Otherwise, another 
process might set the errno between a socket call and testing 
errno. Instead, you must call USAGetLastError() to return 
equivalent codes. It is also possible to use the errno variable 
just as you might have in UNIX by creating a simple macro 
call that uses the USAGetLastErrorf) call. 

Signal Handling 

Signal handling, like the I/O function support, is also limited 
by differences in the DOS, Windows, and UNIX architectures. A 
“signal” is an asynchronous software interrupt sent to your 
application. A signal may originate from another process, the 
same process, or the OS kernel. Signals are installed with the 
signal() function and are caused by calling raise() or as 
the result of a CPU exception-handler. 

The DOS architecture allows for three signals to be 
generated by the OS: SIGABRT (abnormal termination), SIGFPE 
(floating-point error), and SIGINT ( CTRL-C hit). Several other 
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signals are allowable, but can only be sent by your application 
to itself. By contrast, BSD and System V UNIX define more 
than thirty signals between them. The BSD UNIX signals SIGIO, 
SIGURG, and SIGPIPE have special significance for socket ap¬ 
plications (Stevens 1990), and the absence of these signals 
may hinder porting existing UNIX applications to Windows. 
Most code requiring signals can be rewritten with USAAsync 
functions. 

The SIGIO signal is raised whenever any socket owned by 
the process group is ready for asynchronous I/O. The SIGURG 
signal is raised whenever a socket acquires an urgent condi¬ 
tion. This signal normally indicates the arrival of out-of-band 
data on the socket The SIGPIPE signal is raised when an at¬ 
tempt to write data through a socket fails. This usually means 
one or both sides of the communication 
link have already closed the socket. As 
mentioned earlier, the SIGIO and 
SIGURG require some additional setup 
via fnctl() and ioctl() before they 
become live. 


Address and Protocol Family Support 

As mentioned earlier, the BSD socket interface has been 
expanded over the years to support a wide variety of address 
and protocol families. The current list of address families in¬ 
cludes IBM SNA, Digital DECnet, Xerox NS, Apple AppleTalk, and 
a dozen others. However, Windows Sockets 1.0 currently sup¬ 
ports only the Internet address family. To be fair, many of the 
other address families have not made PC implementations 
available. Additional address families may be introduced in 
later versions of the Windows Sockets specification (Hall et al. 
1992: section 1.1). 

The BSD socket interface supports stream, datagram, raw, 
sequenced packet, and reliably delivered message sockets. Of 


Low-Level Domain Name 
System Functions (DNS) 

Last, the Windows Sockets API com¬ 
pletely omits low-level domain name 
functions (see Figure 3). The domain 
name functions perform the mapping 
between hierarchical network names 
and their internet names (i.e., addres¬ 
ses). For example, the host named 
“sharkey.umich.edu" might map to 
129.200.151.003. The domain name 
functions are not necessary for most 
applications. 

The gethostname() and getdomain- 
name() functions return the names of 
the current host and domain respec¬ 
tively (e.g., "sharkey” and “umich.edu”). 
The sethostnameO and setdomain- 
name() functions can choose new 
names for the host and domain. How¬ 
ever, since these last two functions are 
normally executed only by privileged 
processes, their omission from Windows 
Sockets is understandable. This additional 
functionality is currently being considered 
by the Windows Sockets committee. 

Applications making a domain name 
query must first call res_init() and 
then format the query with 
res_mkquery(). Next, the res_send() 
command actually transmits the query 
to a name server and awaits the 
response. Two utility functions, dn_ex- 
pand() and dn_comp(), convert the 
responses to and from full ASCII strings. 
Most local LAN applications will not re¬ 
quire these functions, and they can be 
replaced by calls to get X by Y functions. 
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these five, only stream, datagram, and raw sockets would be 
of interest to Windows Sockets applications using the Internet 
address family. Windows Sockets currently supports stream 
and datagram sockets but not raw sockets. Raw sockets are 
used for the Internet Control Message Protocol (ICMP). Most 
applications will not need ICMP support. 

Windows Sockets Extensions to BSD 

The Windows extensions to the BSD socket library provide 
initialization functions, asychronous database functions, 
asynchronous select, and blocking I/O handling. Each of the 16 
functions in the extensions starts with the prefix WSA (see Fig¬ 
ure 4). Many of them provide alternate methods for achieving 
the functionality of existing BSD calls. 

Initialization Functions 

The initialization functions USAStartupO and 
USACleanupO are better described as new requirements 
rather than new extensions. Your application must call 
USAStartupO before making any other Windows Sockets call. 
The first parameter is the minimum API version level required; 
the other parameter is a pointer to a USAData struct that 
returns important configuration information, including the cur¬ 
rent API version, the maximum number of sockets available, 
the maximum UDP datagram size, and special vendor-specific 
data. The USACleanupf) function shuts down the Windows 
Sockets API and must be the final call your application makes. 
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Asynchronous Database Functions 

The USA GetXByY calls provide an asynchronous alterna¬ 
tive to the blocking BSD calls (see Figure 4). Some TCP/IP con¬ 
figurations use NIS database servers rather than local files for 
database lookup. This implies that a simple gethostbyname() 
call could block your application for as long as it takes to get 
an answer or a network timeout. In Windows Sockets, the 
corresponding USAAsyncGetHostByName() function starts a 
new task for the query and returns its handle. 

The primary calling difference between the BSD and 
asynchronous GetXByY functions is that the latter require a 
window handle (hUnd) and message parameter (wMsg). When 
complete, the task notifies your application by posting the 
message parameter back to your window. This signifies that 
the task has filled in the relevant data structure (e.g., servent) 
for your specific call. Windows Sockets implementations may 
have a limit on the number of simultaneously pending 
asynchronous operations. Accordingly, if an asynchronous 
query returns USAEU0ULDBL0CK .then you may need to abort 
the previous pending query with USACancelAsyncRequest (). 

Asynchronous Select 

The BSD UNIX select() function is the usual method by 
which servers wait for a reply when more than one client 
may be connected. The select() function blocks the caller 
until one or more sockets are eligible for reading, writing, or 
error reporting. Since the sets of flags for each event type are 
independent, you can specify your interest in each event on a 
per-socket basis. A timeout parameter allows select() to 
abort if nothing of interest happens in the specified time 
period. Windows Sockets supports the BSD select () func¬ 
tion and also supports an asynchronous selection via U- 
SAAsyncSelectf). 

Unlike selectf), which handles a large set of sockets 
simultaneously, USAAsyncSelect() must be called once for 
each socket of interest. The USAAsyncSelect() function can 
notify you when a given socket is eligible for one or more of 
the following: reading, writing, out-of-band data reading, ac¬ 
cepting a connection, completing a connection, and closing. 
The notification mechanism is the same as described earlier 
for the asynchronous database functions. The only difference 
is that the l Pa ram of the notification message contains the 
event code (e.g., FD_READ) in the low word and an error code 
in the high word. 

For a given socket, USAAsyncSelectf) sends only one 
notification per event until that event is fulfilled. For example, 
Windows Sockets sends an FD_READ notification as soon as 
data arrives. If more data arrives before the application actual¬ 
ly reads it (e.g., recv() ), then no additional notifications are 
sent. 

Blocking I/O Handler 

The Windows blocking I/O functions are perhaps the most 
important extension to the BSD sockets model. There are 
many situations in which your application might want to use 
blocking I/O. For example, if a client is waiting for a response 
from its server, then a blocking recv() would be appropriate. 
However, since Windows follows a nonpreemptive multitasking 
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model, this would effectively block all Windows applications 
running in your system until the recv() completed. For¬ 
tunately, Windows Sockets provides a built-in blocking hand¬ 
ler to prevent such a system-modal condition. 

The blocking handler intercepts calls which cannot com¬ 
plete immediately and enters a special message-dispatching 
loop. This general technique is also known as the inner loop" 
method of CPU sharing (Smith 1992). Basically, the handler 
looks ahead with PeekMessage() and then performs 
TranslateMessage() and DispatchMessage() as necessary. 
Meanwhile, it also checks periodically for the completion of the 
blocking call or a call to WSACancelBlockingCall (). You can in¬ 
stall your own custom handler with USASetBlockingHook() and 
restore the default handler with WSAUnhookBlockingHook(). 

However, any blocking handler can run only a single block¬ 
ing request at a time. If your application issues any other Win¬ 
dows Sockets call while a blocking request is running, then 
that call will fail and return the USAEINPROGRESS error code. 
Even the WSAAsyncSelect() calls are prevented from execut¬ 
ing during a blocking call. The only valid Windows Sockets 
calls at this point are USAIsBlockingO, which would return 
TRUE, and WSACancelBlockingCall (), to abort the operation. 
Regardless of which handler you use, your application must 
ensure that data passed to blocking functions remains un¬ 
modified for the duration of blocking. 

Conclusion 

Admittedly, Windows Sockets has a few discrepancies at 
the source level with the 4.3BSD UNIX sockets interface. How¬ 


ever, Windows Sockets applications will work unmodified on 
any Network Operating System (NOS) supporting this DLL 
library interface. The major TCP/IP NOS vendors — FTP Software 
(PC/TCP), Sun Microsystems (PC-NFS), Beame & Whiteside (BW- 
NFS), and NetManage (NEWT-SDK) — have already released or 
committed to release Windows Sockets support. The success 
of the Windows Socket specification also appears likely to 
stimulate the emergence of further vendor-independent APIs 
such as WinRPC (a common RPC API for Windows). If you need 
NOS-independent client/server support on TCP/IP for your win¬ 
dows application, Windows Sockets is a plug-and-play solution. 
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A Drag-and-Drop Custom 
Edit Control 

Part 3 

Ron Burk 


This article concludes my look at a custom edit control that provides the drag- 
and-drop features of Word for Windows v2.x. In this final installment, I look at the 
algorithm for placing the text caret correctly and then clear up some loose ends and 
summarize some of the bugs I uncovered while working on the code. 

Placing the Text Caret 

To briefly recap the problem, dndedit lets you grab selected text with the 
mouse, drag it elsewhere in the edit control, and drop it, providing a simpler alterna¬ 
tive to using the clipboard to move text around. While the user is dragging the text 
with the mouse, dndedit continuously displays a text caret that shows where the 
text would be inserted if the mouse button were released. 

Placing the text caret has two obvious complications. First, even though the 
mouse can appear at any pixel on the screen, dndedit must restrict the text caret to 
“whole" character positions. In other words, as you move the mouse slowly straight 
up, the text caret stays in one place until the mouse cursor crosses a text line 
boundary, and then the caret jumps up a line. Likewise, as you move the mouse 
slowly to the right, the caret stays in the same place until you cross over the next 
character, and then the caret jumps over a character. Second, the user may move 

the mouse totally outside the edit control in order to 
cause scrolling to get to the desired destination; dndedi t 
has to place the text caret in a reasonable position in 
the edit control window, no matter where the mouse 
moves on the screen. 
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Figure 1 Positioning the text caret 


static 

int DndPlaceCaret(DNDEDIT *this, POINT FAR *CaretPos) 

( 

int Draglt; 

int LineNumber, LineLength, HalfWidth; 

size_t CharPos; 

char FAR ‘LineText; 

HDC DC; 

long Coord, XCoord, MinXCoord; 

int X, Y, MaxY, LinesInWindow; 

POINT CursorPos; 

HGDIOBJ OldFont; 

GetCursorPos(&CursorPos); 
ScreenToClient(this->HWindow, ACursorPos); 


X ■ CursorPos.x; 

Y = CursorPos.y; 

this->HDrag - 0; 
this->VDrag » 0; 

LinesInWindow * (this->TextRect.bottom 

- this->TextRect.top) / this->FontHeight; 
MaxY = LinesInWindow * this->FontHeight 
+ this->TextRect.top - 1; 
if(X < this->TextRect.left) 

{ 

X * this->TextRect.left; 

this->HDrag = -1; 

) 

else if(X > this->TextRect.right) 

{ 

X » this->TextRect.right; 

this->HDrag = 1; 

1 

if(Y < this->TextRect.top) 

{ 

Y » this->TextRect.top; 

this->VDrag - -1; 

) 

else if(Y > MaxY) 

{ 

Y - MaxY-2; 


this->VDrag ■ 1; 

) 

LineNumber - (int) ((Y - this->TextRect.top + this->VScroll) 

/ this->FontHeight); 

LineNumber ■ MAX(MIN(LineNumber, GetNumLines(this)-l), 0); 

Y = (int)((long)LineNumber * this->FontHeight 

- this->VScroll + this->TextRect.top); 

DC * GetDC(this->HWindow); 

if(this->Font) 

OldFont * SelectObject(DC, this->Font); 

this->InsertionPos ■ GetLineIndex(this, LineNumber); 
LineLength = GetLineLength(this, LineNumber); 

LineText = MemGetLine(this, LineNumber, LineLength); 
if(LineText != NULL) 

{ 


CharPos * 0; 

MinXCoord = MAX(X - this->FontWidth, 0); 
do { 

Coord * GetTextExtent(DC, LineText, CharPos); 

XCoord * LOWORD(Coord) + this->TextRect.left - this->HScroll; 

++CharPos; 

} while(CharPos <= _fstrlen(LineText) && XCoord < MinXCoord); 
HalfWidth = (this->TextRect.right - this->TextRect.left) / 2; 
if(XCoord < (this->TextRect.left + this->FontWidth / 2)) 

{ 

this->ScrollCorrection = (this->TextRect.left - XCoord) 

+ HalfWidth - this->FontWidth; 
this->HDrag = -1; 

) 


else 


Page 20 - Windows/DOS Developer’s Journal 


December 1992 











Figure 1 shows the C version of 
PlaceCaretO, the function that hand¬ 
les correct caret positioning. As I men¬ 
tioned last month, PlaceCaretO also 
supplies information related to drag 
scrolling. The function begins by deter¬ 
mining the placement of the mouse 
cursor with respect to the rectangle 
that encloses the text in the edit con¬ 
trol. PlaceCaretO sets the instance 
variables HDrag and VDrag to indicate 
the direction in which dragging should 
occur if the mouse cursor lies outside 
the edit control. Note that you can drag 
in both a horizontal and vertical direc¬ 


tion simultaneously. If the mouse lies 
outside the text formatting rectangle, 
PlaceCaretO clips the corresponding 
coordinate to lie within the rectangle. 

Next, PlaceCaretO determines the 
correct vertical position for the text 
caret. The hard work has already been 
done and VScroll contains the critical 
information: how much vertical scrolling 
is currently in effect The instance vari¬ 
able HScroll specifies the amount of 
horizontal scrolling currently in effect, 
but that still leaves plenty of work for 
PlaceCaretO. 


New Version 4.5 


Commenting Disassembler! 


Sources 


□ See how programs work 

□ Easily modify programs 

"Sourcer is the best disassembler 
we’ve ever seen." pc Magazine 


SOURCER ™ creates commented source 
code and listings from executable files or 
memory, suitable for reassembly. Sourcer 
helps clarify the inner workings of programs, 
with detailed in-line comments on interrupts, 
subfunctions, I/O ports functions, and much 
more. It offers complete support for all 
8088/87 to 80486 instructions and V20/V30. 
Sourcer provides the most comprehensive 
automatic analysis available to accurately 
separate code and data. It determines data 
types, uses descriptive labels for BIOS and 
PSP data, and links data items across 
multiple segments. Now supports MASM 
6.0, TASM and DOS 5.0. 

Professionals consistently chose Sourcer 
because of its ability to achieve far superior 
results with the least effort. 


Windows 


Windows Source™ works with Sourcer to 
generate detailed listings of Windows EXEs, 
DLLs, VxDS, and OS/2 files. See the actual 
Windows module names used in the programs 
you analyze. Learn the undocumented 
Windows functions used by the professionals 
to perform tricks that are otherwise impossible. 
Purchase with Sourcer and save $30. 


BIOS Source 


for PS/2, AT, XT, PC and Clones 

□ Change and add features 

□ Clarify Interfaces 

The BIOS Pre-Processor™ augments Sourcer 
to obtain commented listings for any BIOS 
ROM in your PC. Now you can understand 
how your specific BIOS works. Adds over 
75K of comments specific to your BIOS. 
Tracks and identifies multiple interrupt 
branches with special labeling such as 
"int_10_video." Full automatic operation. 


Sourcer -Commenting Disassembler $129.95 

BIOS Pre-Processor 49.95 

Sourcer w/BIOS-(save $10) 169.95 

Unpacker -Unpacks packed files 39.95 

View-lt -View 132 column files 69.95 

ASM ProPak I -All above (save $40) 249.80 

ASMtool 486 -Automatic flowcharter 199.95 

ASM ProPak II -All above (save $90) 399.75 


ASM Checker -Finds source code bugs 179.95 
ASM ProPak III -All above (save $120) 549.70 
Windows Source -requires Sourcer v4.5 129.95 

Windows Source and Sourcer 229.90 

Shipping: USA $6; Canada/Mexico $10; Other $18. CA residents 
add sales tax. © 1992 VISA/MasterCard/COD accepted. 

30-DAY MONEY-BACK GUARANTEE 

1-800-648-8266 

\^ '/// V Communications, Inc. 

\T\jy 4320 Stevens Creek Blvd., Suite 275 
7 San Jose. CA 95129 FAX 408-296-4441 
V 408-296-4224 


Figure 1 continued 


this->Scro11Correct!on = 0; 
if(this->ScrollCorrect!'on == 0 && this->HDrag »« 1 && 
(XCoord < (this->TextRect.right - HalfWidth))) 
this->HDrag = 0; 

X * (int)MAX(this->TextRect.left, XCoord); 
this->InsertionPos +* CharPos-1; 

MemF reeLine(LineText); 

) 

if(this->Font) 

Se1ect0bject(DC, OldFont); 

ReleaseOC(this->HWindow, DC); 

CaretPos->x = X; 

CaretPos->y = Y; 

Draglt » this->HDrag || this->VDrag; 

return Draglt; 

} 


Figure 2 Handling keyboard events 


static 

void WMDndKeyDown(DNDEDIT ‘this, MESSAGE FAR ‘Message) 

{ 

int StartPos, EndPos; 

if(this->Grabbed && (Message->wParam *■ VK_C0NTR0L)) 
this->CopyOnly * TRUE; 
if(!this->Grabbed) 

{ 

GetSelection(this, AStartPos, AEndPos); 

if(StartPos != EndPos && ((GetKeyState(VK_SHIFT)&0x8000) == 0) 
&&(Message->wParam «« VK_LEFT || Message->wParam == VK_RIGHT)) 
( 

if(Message->wParam ** VK_LEFT) 

SetSelection(this, StartPos, EndPos); 
else if(Message->wParam ■■ VK_RIGHT) 

SetSelection(this, EndPos, EndPos); 

) 

else 

{ 

if(StartPos ** EndPos) 

DndStartSelection(this); 

DefWndProc(this, Message); 

GetSelection(this, AStartPos, AEndPos); 
if(StartPos »« EndPos) 

DndStartSelection(this); 

el se 

DndStopSelection(this); 

} 

) 

} 
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To determine the correct horizontal 
placement for the text caret, Place- 
Caret () has to first extract a copy of 
the line from the edit control. With that 
in hand, the problem is to use GetText- 
Extent() to figure out the client coor¬ 
dinate position of the nearest (propor¬ 
tionally spaced) character. I simply start 
at the beginning of the line and keep 
adding characters until GetText- 
Extentf) tells me I've passed the posi¬ 
tion of the mouse cursor. This brute 
force approach seems to work fine, but 
you could also do a binary search to 
find the best position if efficiency be¬ 
came a concern. 

As I noted in Part 2, proportionally 
spaced characters are not the only 
problem in determining the horizontal 
placement. Suppose the mouse cursor 
is on a line that is longer than all the 
others currently in view and suppose 
you have dragged the text cursor to the 
end of this line, leaving the others 
scrolled out of sight to the left. If, at 
that point, you move the mouse cursor 
down a line, the text cursor should ap¬ 
pear at the end of the new, shorter 
line. Since that line is scrolled out of 
sight to the left, however, l wanted the 
line to jump into sight. Also, when 
scrolling a line to the left, I did not want 
it to scroll out of sight. In fact, I found it 
more pleasing if horizontal scrolling 


stopped when the right end of the line 
was midway between the left and right 
edges of the edit control. 

To handle these cases, Place- 
Caret () checks to see if the text caret 
would be out of sight to the left. If so, it 
calculates ScrollCorrection, which 
tells how much the edit control would 
have to be scrolled to make the text 
caret appear roughly in the center of 
the window. PlaceCaretf) makes a 
check to see if it has already scrolled 
the line as far to the left as it cares to 
and, if that is the case, sets HDrag to 
zero. Otherwise, dndedit would con¬ 
tinue to generate EM_LINESCROLL 
events and the result would be an an¬ 
noying jumping and flickering. 

Keyboard Messages 

dndedit has to intercept WM_KEYDOWN 
messages and Figure 2 shows the C 
code that handles this task. When in 
the grabbed state, dndedit ignores all 
keystrokes except the control key, 
which the user presses to perform a 
copy rather than a move. If not in the 
grabbed state, then the code has to fig¬ 
ure out whether the selected text has 
changed and, if so, revise the starting 
and ending character positions of the 
selection by calling StartSelection() 
and StopSelection() appropriately. 


The UM_KEYDOUN also contains one of 
the few cases where I decided to make 
a subtle alteration to the basic edit con¬ 
trol user interface. If you have selected 
a single character and you press the 
right arrow key, what should happen? 
The basic edit control will deselect the 
current character and move the text 
caret one character to the right. I 
preferred Word for Windows’ behavior, 
so I wrote code to simply deselect the 
selected text and position the caret at 
one end or the other (depending upon 
which arrow key was pressed) of the 
former selection. 

Mouse Button Events 

Two other event handlers I have not 
displayed take care of the mouse but¬ 
ton. When the user presses the left 
mouse button, the code in Figure 3 
takes over. If the cursor is not over the 
selected text, then it merely means the 
beginning (potentially) of a new text 
selection. Otherwise, the code changes 
both the mouse cursor and the text 
caret to their “grabbed" shapes. One 
small but important check is to see if 
the control key is currently depressed. 
Allowing the user to press the control 
key (to specify a copy rather than a 
move operation) before as well as 
during the dragging of the text is simply 
a convenience. 

Figure 4 shows the TPW version of 
the handler for left-button-up events. If 
not in the grabbed state, then the code 
simply calls StopSelection() to mark 
the (potential) end of a text selection. 
Otherwise, it is time to deposit the 
dragged text in a new position. Place- 
Caret () has marked the correct charac¬ 
ter position in the variable Insertion- 
Pos. After restoring the shapes of the 
text caret and mouse cursor, the code 
either moves or copies the text to its 
new position, based on whether Copy- 
Only was set or not. Emulating Word 
for Windows, if the InsertionPos is 
within the originally selected text, then 
the code just deselects the text; other¬ 
wise, the text is left selected in its new 
position within the edit control. 

An Overview 

If you build a custom control by 
subclassing an existing one, as dndedit 
does, one good way to summarize the 
code is by listing the window messages 


Figure 3 Code to grab the text selection 


procedure TDndEdit.WMLButtonDown(var Message:TMessage); 
var 

CaretPos : TPoint; 
begin 

if InSelection(TPoint(Message.LParam)) then { if grabbing selection ) 
begin 

CopyOnly := ((GetKeyState(VK_CONTROl) AND $8000) = $8000); 
SetCapture(HWindow); 

Cursor := Cross; { Not really required since mouse is captured } 
SetCursor(Cross); 

ShowCaret(FALSE); 

CreateCaret(HWindow, 1, 2*GetSystemMetrics(sm_CXB0RDER), FontHeight); 
PlaceCaret(CaretPos); 

SetCaretPos(CaretPos.X, CaretPos.Y); 

CaretBlinkTime := GetCaretBlinkTime; 

SetCaretBlinkTime($FFFF); 

( Explicit ShowCaret() required after CreateCaret() } 

ShowCaret(TRUE); 

Grabbed := TRUE; 

end 
else 
begin 

DefWndProc(Message); 

StartSelection; 

end; 

end; 
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it intercepts and specifying what actions 
it takes for each message. Here is an 
overview of dndedi t in that format: 

• EM_SETSEL — Revise the starting and 
ending selection character positions 
and update the selection rectangles. 

• EM_LINESCROLL — Before passing on 
the message, check to see if the 
control is already scrolled to the 
maximum or minimum desired verti¬ 
cal or horizontal direction. If so, set 
that component to zero. 


• UM_HSCROLL — Update current 
amount of horizontal scrolling («- 
Scroll). 

• UM_KEYDOUN —If in grabbed state and 
user is pressing control key, set 
CopyOnly flag to TRUE. If not in 
grabbed state, check to see if user is 
changing the selection in some way. 
Revise the current selection rec¬ 
tangles appropriately and remember 
where the selection begins and 
ends. 


Figure 4 The WM_LBUTT0NUP Handler 


procedure TDndEdit.WMLButtonUp(var Message:TMessage); 
var 

SelectionSize, StartPos, EndPos 
: integer; 

Buffer 

: PChar; 

begin 

Drag := 0; 
if Grabbed then 
begin 

ShowCaret(FALSE); 

ReleaseCapture; 

CreateCaret(HWindow, 0, Z*GetSystemMetrics(sm_CXBORDER), FontHeight); 
SetCaretBlinkTime(CaretBlinkTime); 

ShowCaret(TRUE); 

Cursor := 0; 

StartPos := SelectionStart; 

EndPos := SelectionEnd; 
if StartPos > EndPos then 
SwapInt(StartPos, EndPos); 

if (InsertionPos >= StartPos) AND (InsertionPos < EndPos) tnen 
begin 

Grabbed := FALSE; 

SetSelectionflnsertionPos, InsertionPos); 
end 
else 
begin 

SelectionSize := abs(StartPos-EndPos); 

GetMem(Buffer, SelectionSize+1); 

GetSubText(Buffer, StartPos, EndPos); 
if CopyOnly = FALSE then 
begin 

DeleteSelection; 

if InsertionPos >* StartPos then 

InsertionPos := InsertionPos - SelectionSize; 

end; 

SetSelection(InsertionPos, InsertionPos); 

Insert(Buffer); 

Grabbed := FALSE; 

SetSelection(InsertionPos, InsertionPos+SelectionSize); 
FreeMem(Buffer, SelectionSize+1); 
end; 

{ Explicit ShowCaretO required after CreateCaret() } 
end 
else 

StopSelection; 

DefWndProc(Message); 

end; 
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Windows Help Files 
So easy - it’s Magic! 


The Windows Help Magician saves you 
countless hours creating custom help files' 
for Microsoft Windows applications. 

Forget about the cumbersome footnote 
way of creating help with Microsoft 
Word. Use this tool to create help files in 
a single, integrated environment. No 
need to switch out to DOS to run the Help 
Compiler. With the Magician you’ll be 
able to write the RTF file 
instantaneously. And you can even 
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Microsoft Word. 
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files 
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• Test your help file instantaneously 
while inside the Help Magician 

• Works with all Windows languages 

• Supports Windows 3.0 and 3.1 
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• WM_LBUTTONDBLCLK -Pass the message on, then call Start- 
Selectionf) and StopSelection() to revise the selected 
text rectangles. 

• HM_LBUTTONDOUN — If the mouse cursor is within the 
selected text rectangles, then capture the mouse, switch to 
the grabbed state, and change both the text caret and the 
mouse cursor. Otherwise, simply pass the message on and 
call StartSelectionf) to note the beginning of a new text 
selection. 

• HM_LBUTTONUP — If in the grabbed state, then release the 
mouse, return the cursor and caret to their non-grabbed- 
state shapes, exit the grabbed state, and either move or 
copy the selected text to InsertionPos, based on the 
state of Copy On ly. If not in the grabbed state, pass the 
message on and call StopSelection() to note the possible 
end of text selection. 

• UM_MOUSEMOVE - If not in the grabbed state, set the cursor 
based on whether it is over the text selection rectangles or 
not. If in the grabbed state, invoke complicated logic to 
position the text caret and generate a scroll event, if 
necessary. 

• UM_SETCURSOR - If other code has specified a particular cur¬ 
sor, set the cursor to that. Otherwise, pass the message on 
to edit control. 

• UM_SETFONT — Pass the message through, then store a 
handle to the new font in Font, and call GetTextMetrics() 
to revise FontHeight. 


Btrieve C++ Libraries 

...and Now for C and Visual Basic 

Discover how easy Btrieve development can be with OOP technology. Adding to 
our powerful and popular C++ library for Btrieve we now introduce three new 
products that futher extend OOP technology to Btrieve development under C, C++ 
and Visual Basic. 

Btrv++ is a library of 12 major classes that make Btrieve development a snap. 
Position block, key and data buffer management. Create objects that know their 
own file structure. You can even have objects share the same file resources in any 
mode. Implementation of all Btrieve operations as member functions as well as 
many value added functions for file and index creation, extended operations, 
simplified multi-user locking, and much much more. Through inheritance only one 
object class is all you need to write complete Btrieve applications. Supports all 
Btrieve environments; DOS, Windows and OS/2. Compatible with Borland C++ 

3.x, MS C7.0 and many others. Static library and Windows DLL. Royalty free. Full 
source code and set of sample programs. $349. 

New! Btrvgen-H- is a combination class\code generator and data dictionary for 
Btrv++. Describe tables, columns, keys, and relationships via easy to use Windows 
dialogs; then generate royalty free classes implementing your tables, keyed access 
paths, relationships and common operations. Runs under Windows. Generated code 
supports Windows, DOS and OS/2. Requires Btrv++. Sold separately $229. Order 
both Btrv++ and Btrvgen++ together for a special price of $449. 

New! CBtrv combines C and C++ to create a library of unsurpassed capability. 
Brings OOP technology to standard C programming. Powerful and easy to use. 
Windows and OS/2 DLLs. Full set of sample programs. Royalty free. $249. With 
source code. $389. 

New! VBtrv combines C, C++ and Visual Basic to produce a library of unrivaled 
capabilities, speed and ease of use. Brings the power of OOP technology to Btrieve 
development under Visual Basic. Btrieve development has never been easier. A 
Windows DLL. Full set of sample programs. Royalty free. $249. With source $389. 

Btrv++„ VBtrv. 

Btrvgen++, CBtrv,. 
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• WM_VSCROLL - Update the current amount of vertical 

scrolling (VScroll). 

Microsoft’s Knowledge Base 

The Microsoft Knowledge Base (GO MSKB) is a forum on 
CompuServe that contains an indexed database of technical 
information, much of it related to Windows programming. This 
is a great resource if you have access to CompuServe, and I 
have more than once obtained the answer to a technical 
question after just a few minutes of searching. 

While looking for other information in the Knowledge Base, 

I came across document number Q68572, entitled "Caret Posi¬ 
tion & Line Numbers in Multiline Edit Controls,” an article that 
shows how to obtain the same effect as EM_GET- 
FIRSTVISIBLELINE, even if you are running under Windows 
3.0. Since dndedit has to perform much the same calculation, 

I downloaded this article and studied it. 

This document was very helpful because it pointed out a 
couple of bugs in my code. To my surprise, the algorithm in 
this document used the TEXTMETRIC parameter tmHeight for 
the height of edit control lines, rather than tmHeight + tm- 
ExternalLeading, as dndedit used. It turns out that while I 
had tried different fonts with dndedit, I had not tried a font 
that had significant external leading. In fact, the Knowledge 
Base algorithm is correct, so I have since changed dndedit to 
use just tmHeight for the height of lines. That still leaves the 
puzzling question of why Windows' standard edit control ig¬ 
nores the interline spacing specified by the font designer. 

The other problem that the document pointed out in my 
code was also related to font handling. I simply was ignorant 
of the transitory nature of device contexts, so I had to go back 
and change dndedit to first get the current font, then select it 
into the edit control's device context before calculating font 
parameters. 

I continued to study this document because it seemed to 
offer a simple algorithm for determining the first visible line 
number in an edit control — much simpler than the algorithm 
used by dndedit. I soon discovered that the reason the algo¬ 
rithm was quite simple was that it was quite wrong! First, the 
document simply ignores the possibility that the edit control 
might have scroll bars; the simple algorithm depended upon 
the text caret's always being visible in the window. Second, 
Microsoft's simple algorithm failed to consider that the text 
caret might be at either end of the selected text. Ignoring this 
nasty problem made their code simpler, but produced the 
wrong answer if you selected text by moving the mouse or 
arrow keys from right to left instead of vice versa. 

Another interesting bug in the Microsoft code caught my 
eye when I noticed that their algorithm used a while loop to 
calculate the number of lines from the text caret to the top of 
the window — the code subtracts tmHeight from the vertical 
coordinate of the text caret until the result is less than or 
equal to tmHeight. I puzzled over why anyone would use a 
loop instead of simple arithmetic. Suddenly I realized that they 
had forgotten to subtract the vertical offset of the edit 
control’s text formatting rectangle. Sure enough, if I sent an 
EM_SETRECT to move the edit control text formatting rectangle 
downward and then ran their code, it gave wrong answers. It 
seems likely that the author used a simple division, discovered 
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that the answer wasn't quite right, and then hit upon an ad 
hoc loop that seemed to work. 

I reported the problems in this particular Knowledge Base 
article to Microsoft and they have since removed it for repairs. 
It will be interesting to see if it reappears, since there appears 
to be no easier way to solve this problem than the rather 
tedious algorithm dndedit uses. 


The surprise was that the bug was still there even when I 
just did a CreateUindow() of the Edit class. After posing the 
question to Microsoft support, I learned that this really is a 
known Windows bug that did not get fixed in Windows 3.1. It 
was an unlucky coincidence that I stumbled on it while writing 
my own code to position the text caret, otherwise I would not 
have wasted so much time searching my own function for errors. 


More Bugs 

Part of the fun of writing software that performs graphical 
operations is that many of your mistakes give you solid visual 
feedback about what you're doing wrong. In the midst of 
writing dndedit, I noticed that the text caret was getting 
drawn outside the edit control window during certain scrolling 
operations. If I positioned the text caret on the bottom line of 
the control and then pressed the scroll button to scroll down 
one line, the text caret suddenly appeared one line below the 
bottom of the text formatting rectangle. A similar thing hap¬ 
pened if I placed the text caret at the left and scrolled to the 
left — the text caret appeared to the left of the edit control 
instead of disappearing. 

Since I was explicitly positioning the caret myself with 
PlaceCaret(), I was certain that that was where the problem 
lay. After more experimentation, though, I could not figure out 
what the problem was, since PlaceCaret() should get called 
only when the user has “grabbed’’ some text and the bug was 
not related to being in the grabbed state. In desperation, I 
decided I would start with a pure edit control and then start 
adding my own code until the bug appeared. 


Summary 

Writing this custom control was a humbling experience. It 
took much longer than I thought and required a lot more low- 
level experience with Windows than I had at the beginning. 
The only reward for all this painful discovery of windows 
anachronisms is that I feel I am now the world’s leading expert in 
the extremely narrow field of locating and managing the position 
of the text caret in an edit control. Much of this hard-won 
knowledge could and should be provided by the Windows API 
documentation. I guess that is what makes writing Windows 
books such a popular pastime for so many programmers! 

I would like to thank Paul Bonneau for answering my Win¬ 
dows questions, as always, whenever I got stuck on this 
project. Paul is looking into the mystery (described in the first 
installment) of why dndedit seems to yield the CPU success¬ 
fully even though its input queue is not empty. If he turns up 
anything interesting, watch for the answer in his column. I 
would also like to thank jeroen Pluimers for giving me feed¬ 
back on the Pascal version of the code. Although I can con¬ 
verse in Pascal without discomfort, it is still a second language 
to me and native Pascal speakers can usually help me im¬ 
prove my idioms. □ 
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Identify the Running DOS 


This article tells you how to obtain the name of the running task in a DOS session 
from a Windows application running in enhanced mode. Input is in the form of a 
window handle of the DOS window and output is a string containing the path of the 
DOS executable. The article also describes some of the pitfalls and unwritten rules of 
writing a simple virtual device driver (VxD). 

A Three-Part Problem 

On the surface this problem sounds simple, but as you may have guessed, it 
turns out to be very non-trivial. There are three components of the problem: first, in 
DOS, how to find the name of the executing application; second, how to communi¬ 
cate the name of the executing DOS application to a Windows application-, and third, 
how to find the virtual machine (VM) running the DOS session given its DOS window. 

As far as I can tell, only the second of these components has a documented 
solution: you need to write a VxD in order to obtain inter-VM information (all Win¬ 
dows applications run in the system VM, each DOS session runs in its own VM). For 
the other two parts, there appears to be no recourse other than to rely on undocu¬ 
mented functionality. Thus the solution I am about to present will work under Win¬ 
dows 3.1, but may well break in a future version of Windows. 

Even though Microsoft apparently does not document how to extract the name 
of the current application under DOS, others have. In particular, the book MS-DOS 
Developer's Guide, by the Waite Group, shows that an application's path follows the 
environment block pointed to in the task’s program segment prefix (PSP). Interrupt 
21, service 0x6200 gets the PSP of the currently executing task and returns it as a 
paragraph into real-mode memory. A real-mode address is then obtained by using 
the paragraph value as a segment prefix with a 0 offset. The environment block, 
which begins at offset 0x2c from the start of the PSP, consists of a set of zero-ter¬ 
minated strings, one per environment variable. Each new string begins after the null 
terminator of its predecessor. After the last environment string are the bytes 0x01 
and 0x00, followed by a string containing the path of the task's executable. What 
the book does not mention is that if no task is running other than the command 
interpreter, command, cow, then the bytes 0x01 and 0x00 are not present and the 
path string is omitted. 

Getting the VM from the DOS window is the sleaziest part of this problem. To 
accomplish it, I used the Soft-lce/W debugger from Nu-Mega Technologies. One of 
the nice features of this debugger is that it allows you to set a breakpoint on a 
particular interrupt service. For example, you can set a breakpoint on interrupt 0x2f, 
service 0x1684, which is used to obtain the protected-mode entry point of a VxD. 
This is exactly what I did, just before invoking a DOS window. The return address is a 
function pointer that the Windows application can use to obtain a service from the 
VxD. The DOS task, UinOldAp, stores this function pointer in a static variable. By 
setting a breakpoint on the callback and getting the return address from the stack, 
you can examine the various values returned from a VxD to UinOldAp. One of these 
values, returned in DX:AX, looked suspiciously like a VM handle and, when I compared it 


Paul Bonneau is a Senior Software Design Engineer at Microsoft He developed a 
library used in several Microsoft products and was a developer of HyperChem, a 
molecular modeling system marketed by Autodesk. The opinions expressed in Paul's 
column are his alone and do not necessarily reflea those of Microsoft 
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Application from Windows 

Paul Bonneau 


with the list of VMs obtained from Soft-lce/W's VM command, turned out to be the 
handle of the DOS VM. This value was stored at location OxOOfc in UinOldAp's DS. 
Now, given a window handle belonging to UinOldAp, you can find its instance handle by 
using GetWindowWord(hwnd, QMJUNSTANCE) octiieGetUindouInstance() macro from win¬ 
dows x.h. But an instance handle is nothing more than a task's data segment selec¬ 
tor, so to access the global containing WinOldAp 's VM handle you can use: 


(LPDWORD)MAKEFP(GetWindowInstance(hwndOldAp, OxOOfc)) 

This is an especially ugly hack, since there is nothing to prevent the location of this 
global from moving in the next version of Windows. 


The DosName VxD Solution 

You now have all the pieces of the puzzle — it's time to put them together. 
Listing 1 is the assembly code for the VxD, DosName. DosName provides three 
protected-mode API services: return the VxD version number, register a callback 
function, and get the name of the current task in a DOS session identified by VM 
handle. After acquiring the address of the protected-mode interface, a client Win¬ 
dows application places one of the constant values —apiGetVersion, apiRegister, 
or apiDosName —in the AX register before calling the interface to request the re¬ 
quired service. Since the VxD provides no other services, its initialization entry point, 
DosNamelnit, is basically a no-op, and its control message dispatcher, DosName- 
Control, has nothing to do either. DosNameApi is registered as the protected-mode 
API interface in the Declare_Virtual_Device macro at the beginning of the VxD. All 
DosNameApi does is compare the service number in the client VM's AX register with 
the list of API service numbers. If it finds a match, execution jumps to the particular 
service routine. 

The simplest of these routines is DosNameGetVersion, which returns the version 
number of the VxD to the client VM's AX register. Every VxD that supports a 
protected-mode API interface is supposed to provide this service when the entry 
point is called with 0 in the AX register. The RegisterClient routine is also simple; 
it stores the address of a callback routine from the calling window applicationvia 
DX:BX. The callback is stored as a selector, offset pair in the global variables pfn- 
NotifySel and pfnNotifyOffset. 

The code to implement the apiDosName service is not so trivial. The biggest prob¬ 
lem is that each VM has its own local descriptor table (LDT) and selectors from one 
VM’s LDT cannot be used in any other VM — to attempt to do so raises a general 
protection violation. Therefore, the VxD must switch from the system VM where it is 
called, to the DOS VM to extract the path of the running DOS application, then back 
to the system VM to supply the path to the Windows client. But switching from one 
VM to another is not a synchronous operation. The VxD must schedule a VM switch 
and supply the address of a callback to invoke when the VM switch occurs. In this 
case two callbacks are required: one to invoke from the DOS VM and another to 
invoke upon return to the system VM. This also explains why a callback from the 
Windows client application is required. Since the VM switches are asynchronous, a 
callback serves to notify the Windows application that the requested data is ready. 
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Each VM maintains a client register structure (CRS) which 
contains the values of the processor’s registers when a VxD 
gains control. So when a Windows application calls the VxD 
via its protected-mode interface, it passes parameters in 
registers. The VxD gets the parameters by extracting them 


Listing 1 dosname.asm 


***************************************************** 

dosname.asm 

-- VxD that returns the name of the currently 
executing DOS app in a given VM. 
***************************************************** 

. 386p 

; Header files, 
include vmm.inc 
include v86mmgr.inc 

; Constants. 
wDeviceld equ 297bH 
bVersionMajor equ 01 
bVersionMinor equ 00 
wVersion 


Device id from Microsoft. 
Major byte of version number. 
Minor byte of version number, 
equ (bVersionMajor * 256 + bVersionMinor) 


cchPathMax 

equ 128 

; Max. size of pathname. 

ibEnv 

equ 2ch 

; Env offset in PSP. 

; API id's. 




apiGetVersion 

equ 0 


; Get version of this VxD. 

apiDosName 

equ 1 


; Get the name of the DOS app. 

apiRegister 

equ 2 


; Register a callback function. 

; Globals. 




VxD_DATA_SEG 




selClient 

dw 

(0) 

; Client buffer selector. 

ibClient 

dd 

(?) 

; Client buffer offset. 

hwndClient 

dw 

(?) 

; Window to notify. 

pfnNotifySel 

dw 

(?) 

; Code selector of callback. 

pfnNotifyOffset dw 

(?) 

; Offset in selector. 

rgchPath 

db 

(cchPathMax + 1) dup (?) 


VxD_DATA_ENDS 
; Device Header. 

Declare_Virtual_Device dosname, bVersionMajor, 
bVersionMinor, DosNameControl, wDeviceld, 
Undefined_lnit_0rder,, DosNameApi 


; Control Procedures. 

VxD_Locked_Code_Seg 

BeginProc DosNamelnit 

★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★Hr******** 

-- Called for protect mode initialization. Not 
much to do. 

clc 

ret 

EndProc DosNamelnit 
BeginProc DosNameControl 

*****************************************************. 

» 

-- Control dispatcher. Not much to do here either. ; 

★ ★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★•A:*. 


Control_Dispatch 

clc 

ret 

EndProc DosNameControl 
VxD_Locked_Code_Ends 

; API's. 


Device Init, DosNamelnit 
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from the client register structure. One of the weird conven¬ 
tions used in writing a VxD is that on entry to a VxD entry 
point, the EBP register contains the address of the client mode 
structure. This is why it is difficult to write a VxD in C; most C 
compilers (if not all) use EBP (or BP in 16-bit mode) as the base 


of the current stack frame — this is, after all, its intended 
usage. 

DosNameTestf) is the routine that implements the apiDos- 
Name service. It receives the VM handle of the DOS session to 
examine, the address of a buffer to receive the path of the 


Listing 1 continued 


VxD_Code_Seg 

BeginProc DosNameApi, Public 
.***************************************************** 
9 

; -- Main dispatch point for protected mode API. 

; — On input: 

; -- Client_EAX : API id to execute. 

; -- Jump to corresponding API routine. 

•★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★•ft*** 

9 

; Innocent until proven guilty (no error yet), 
mov [ebp].Client_Flags, 0 


; Which function is required? 
movzx eax, [ebp].Client_AX 

cmp ax, apiGetVersion 

jz short DosNameGetVersion 

cmp ax, apiDosName 

jz short DosNameTest 

cmp ax, apiRegister 

jz RegisterClient 

; Guilty. Set carry flag to indicate failure, 
or [ebp].Client_Flags, CF_Mask 

ret 

EndProc DosNameApi 


. *****************************************************. 
9 9 

; -- Return the version number. ; 

• ***************************************************** • 
9 9 

BeginProc DosNameGetVersion, Public 
mov [ebp].Client_AX, wVersion 

ret 

EndProc DosNameGetVersion 

•★★★★★★★★★★★★★★★★★★★★Hr********************************* 

; -- Return the name of the currently executing DOS ; 

; task in the given VM. ; 

; -- Schedules a callback for the VM, so that it can ; 
; be examined when it is running (and in memory). ; 

; -- On Entry: ; 

; -- Client_BX, : Low word of VM handle. ; 

; -- Client_CX, : High word of VM handle. ; 

; -- Client_DS, : Buffer to receive name of ; 

; Client_DX : running DOS app. ; 

; -- Client_SI, : Window to receive notification. ; 

•★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★ft* 

BeginProc DosNameTest, Public 

; Make sure we aren't already processing a request, 
test selClient, Offffh 

jnz short DosNameTestExit 


; Get VM from caller. 

mov bx, [ebp].Client_CX 

shl ebx, lOh 

mov bx, [ebp].Client_BX 

; Make sure VM handle is valid. 
VMMCall Validate_VM_Handle 

jc short DosNameTestExit 


; Get window to receive notification, 
mov ax, [ebp].Client_SI 

mov [hwndClient], ax 

; Get a selector for VM's memory. 

VxDCall V86MMGR_Get_VM_Flat_Sel 

or ax, ax 

jz short DosNameTestExit 

movzx edx, ax ; Flat VM sel as ref data. 

; Store the buffer to receive DOS app path, 
mov ax, [ebp].Client_DS 

mov [selClient], ax 

movzx eax, [ebp].Client_DX 

mov [ibClient], eax 

; Schedule the callback that does the work. We 
; already have the handle of the VM in EBX and a 
; flat selector to the VM's memory in EDX. 
mov eax, High_Pri_Device_Boost ; Now! 

mov ecx, PEF_Wait_For_STI or \ 

PEF_Wait_Not_Crit 

mov esi, 0FFSET32 GetDosAppName 

VMMCall Call_Priority_VM_Event 
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Listing 1 continued 


; If VM did not execute, temporarily set its 

; execution focus. 

test esi, Offffffffh 

jz short DosNameTestExit 

VMMCall Set_Execution_Focus 

DosNameTestExit: 

ret 

EndProc DosNameTest 

★ ★★★★★★★★★★★★★★★★★★★★★★★★★★★★★■A:********************** 

-- Call_Priority_VM_Event callback. 

— Issues an int 21, service 6200 to get the 
current PSP, then copies the app name found at 
the end of the environment block. 

-- On entry: 

-- EBX : VM being examined. 

-- EDX : Loword has flat selector for this VM. 
***************************************************** 


BeginProc 

GetDosAppName, Public 

; -- Call Priority VM Event callback. 

push 

edx 

; -- Call the 

client callback to notify 



; has been 

obtained. 

: Get the current PSP for this VM. 

; -- On entry, 

EDX VM handle containing 

Push Client 

State 

. ************************************** 

1 

VMMCal 1 

Begin Nest Exec 

BeginProc NotifyClient, Public 

mov 

[ebp].Client AX, 6200h 

; Copy app path to client's buffer. 

mov 

eax, 2Ih 

xor 

ax, ax 

VMMCal 1 

Exec Int 

mov 

al, BYTE PTR [rgchPath] 

VMMCall 

End Nest Exec 

or 

ax, ax 

movzx 

eax, WORD PTR [ebp].Client BX 

jz short 

CallBack 

shl 

eax, 4 

mov 

edi, [ibClient] 

add 

eax, ibEnv 

mov 

esi, 0FFSET32 rgchPath 

Pop Client 

State 

mov 

ax, [selClient] 



push 

es 

; Find environment block and walk to end. 

mov 

es, ax 

mov 

[rgchPath], 0 

mov 

ecx, cchPathMax 

pop 

edx 

repz movsb 

push 

ds 

pop 

es 

pop 

es 



mov 

ds, dx 

Call Back: 


movzx 

eax, WORD PTR [eax] 

; Call client notification callback 

shl 

eax, 4 

Push Client State 

mov 

edi, eax 

VMMCall 

Begin_Nest_Exec 

EnvWalk: 


; Push VM 

handle. 

cmp 

byte ptr [edi], 0 

mov 

eax, edx 

jne short 

SkipEnvLine 

shr 

eax, lOh 

cmp 

byte ptr [edi + 1], 1 

VMMCall 

Simulate Push 

jne short 

ScheduleNotify ; No app name found. 

mov 

ax, dx 

cmp 

byte ptr [edi + 2], 0 

VMMCal1 

Simulate Push 

jne short 

ScheduleNotify ; No app name found. 



add 

edi, 3 

; Push notification window. Make s 

mov 

esi, edi 

mov 

ax, [hwndClient] 



or 

ax, ax 

; Copy app 

path to global. 

jz 

short NotifyClientExit 

mov 

edi, OFFSET32 rgchPath 

VMMCall 

Simulate Push 

mov 

ecx, cchPathMax 



repz movsb 


mov 

cx, [pfnNotifySel] 



movzx 

edx, [pfnNotifyOffset] 

ScheduleNotify: 


VMMCall 

Simulate Far Call 

; Schedule 

call back to system VM to call client's 

VMMCal1 

Resume Exec 

; notification callback. 



push 

es 

NotifyClientExit: 

pop 

ds 

VMMCal1 

End Nest Exec 

mov 

edx, ebx ; Current VM handle param. 

Pop Client 

State 

VMMCall 

Get Sys VM Handle 



mov 

eax, High Pri Device Boost 

; Reset for next time. 

mov 

ecx, PEF Wait For STI or \ 

mov 

[selClient], 0 


PEF Wait Not Crit 

ret 


mov 

esi, offset32 NotifyClient 

EndProc NotifyClient 

VMMCall 

Cal 1 _Priority_VM_Event 




jmp short GotName2 
SkipEnvLine: 

; Skip characters until null, 
mov ecx, cchPathMax 

mov al, 0 

repne scasb 
or ecx, ecx 

jnz short EnvWalk ; Make sure there is a 


null. 


GotNamel: 

push 

pop 

GotName2: 

ret 

EndProc 


es 

ds 


GetDosAppName 


★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★Hr****************** 
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executing DOS application, and a window handle to pass back 
to the notification callback. The reason for saving a window 
handle here is that when a callback in the Windows client is 
invoked, not only is SS != DS, but neither SS nor DS is that of 
the client! So the callback cannot extract a window handle 
from a global variable. In fact, the only officially sanctioned 
operation the callback can take is to call PostMessagef). 

DoNomeTestO stores the parameters extracted from the 
CRS in the global variables selClient, ibClient, and hwnd- 
Client. The VM handle is extracted from CX:BX and placed in 
EBX. It would be simpler if the client could simply set EBX 
before calling the VxD, but for Microsoft’s C7 compiler this is 
not possible. The C7 compiler does not allow 32-bit operands 
using the _asm directive. The virtual machine manager (VMM) 
service Validate_VM_Handle is used to prevent all hell from 
breaking loose if the client application passes in a bogus value 
for the DOS session's VM handle. A general protection violation 
inside a VxD is not a pretty sight. 

If all went well, the virtual 86 mode memory manager, 
V86MMGR, is called to obtain a selector to the DOS VM's address 
space. It is my experience that this must be done in the sys¬ 
tem VM; all attempts to get it to work in a DOS VM failed. The 


Listing 1 continued 


.***************************************************** 
; — Register the client's callback function. 

; -- Client_DX, : Pointer to callback to invoke 

; Client_BX : when path obtained. 

•*★**★★★*★**★**★★★★★★★**★★★★*★★*★*★****★*★*★★*★★****★★ 

BeginProc RegisterClient, Public 

; Store address of notification callback. 


mov 

ax, [ebp].Client_BX 

; Offset. 

mov 

[pfnNotifyOffsetT, ax 


mov 

ax, [ebp].Client_DX 

j Selector 

mov 

ret 

[pfnNotifySel], ax 


EndProc 

RegisterClient 


VxD_Code_ 

End 

Ends 



; End of File 


Listing 2 dosname.h 


y***************************************************** j 

/* dosname.h */ 

/* -- Interface to DosName VxD. */ 

y***************************************************** y 
/* VxD ID from Microsoft. */ 

#define wDosNameDeviceld 0x297b 

/* Current version of VxD. */ 

Idefine wDosNameVersion 0x0100 

/* Return VxD version number. */ 

Idefine apiGetVersion 0 

/* Return name of current DOS app in given VM. */ 
Idefine apiDosName 1 

/* Register callback function with VxD. */ 

Idefine apiRegister 2 

/* End of File */ 


documentation, however, mentions nothing about this. Having 
obtained the selector, you might ask, why not just examine 
the DOS VM’s memory now, instead of having to schedule VM 
switches? The answer is that this selector is only valid in the 
DOS VM since it is a local descriptor. Also, the PSP for the DOS 
application is returned via an interrupt, not by examining 
memory. It may be the case that interrupt 0x21, service 
0x6200 simply returns the address of a global, but this solu¬ 
tion already relies on too many undocumented facts as it is. 


Listing 3 

dosname.def 



;; dosname.def 



» • 

;; -- Linear linked definition 

file for DosName ;; 

;; VxD. 



> > 

LIBRARY DosName 




DESCRIPTION 

'DOS app 

name utility' 

EXETYPE 

DEV386 



SEGMENTS 




LTEXT 

PRELOAD 


NONDISCARDABLE 

LDATA 

PRELOAD 


NONDISCARDABLE 

TEXT 

CLASS 

'PC0DE' 

NONDISCARDABLE 

DATA 

CLASS 

'PC0DE' 

NONDISCARDABLE 

EXPORTS 




dosname 

_DDB 
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Finally, the VMM routine Call_Priority_VM_Event is 
called to schedule a switch to the DOS VM. The documenta¬ 
tion implies that this is all that is necessary to achieve the 
switch, but I have found this is not the case. If the DOS ap- 


Listing 4 makefile 


####################################################### 
tit makefile tt 

## -- Project file for DosName VxD. tt 

ttttttttttttttttttttttttttttttttttttttttttttttttttttttt 
all: dosname.386doslist.exe 

dosname.386: dosname.obj dosname.def 

link386 dosname.obj,dosname.386 /NOI /NOD /NOP \ 
/MAP,,.dosname.def 
addhdr dosname.386 
mapsym32 dosname 
copy dosname.386 \win\system 

doslist.exe: doslist.obj doslist.def doslist.rc \ 
makefile 

link /NOD/map doslist,,, libw slibcew, doslist.def 
rc $(DEFS) doslist 
mapsym doslist 

doslist.obj: doslist.c 

cl -c -AS -G2w -Od -Zdpe -W3 -DSTRICT $(DEFS) \ 
doslist.c 

dosname.obj: dosname.asm 

masm5 -p -w2 -Mx -Zd dosname; 


plication is not in the foreground, or does not have the back¬ 
ground option set from its Settings dialog, the switch never 
happens; it just gets queued up. If the user later brings the 
DOS window to the foreground, the callback supplied to 
Call_Priority_VM_Even gets called over and over, once for 
each scheduled switch. A trick to use here is the VMM call 
Set_Execution_Focus. If Call_Priority_VM_Event returns 
zero, the DOS VM was successfully switched and you are 
done. If not, the switch is scheduled for a later date, which 
may be never if the DOS VM does not gain control through 
user intervention. At this point you can force the VM switch 
by calling Set_Execution_Focus. 

The callback invoked in the DOS VM, GetDosAppName, does 
most of the real work. It uses the VMM’s Exec_Int routine to 
perform a real-mode interrupt in the DOS VM to get the PSP. 
This routine can only be used from within a nested execution 
block delineated by the VM services Begin_Nest_Exec and 
End_Nest_Exec. Within such a block, any changes to the 
machines registers are reflected in the VM's client register 
structure, which means that the contents of the structure 
should be saved just before you enter the block and restored 
just after you leave it The macros Push_Client_State and 
Pop_Client_State perform this service, but be careful: they 
use the stack to save the data without bumping up the stack 
pointer, so you must not push or pop from inside the nested 
execution block (another goody Microsoft forgot to tell you). 

With the PSP in hand, the remaining 25 lines of code skip 
over the PSP's environment strings looking for the pair of 
bytes, 0x01 and 0x00, that would precede the application’s 


Listing 5 dosiistc 


/****★*★**★*★★*★******★****★★★★★*★*★****★*★***★*****★*i 

{ 

/* doslist. c */ 

MSG msg; 

/* -- Enumerate all DOS boxes in the system, and */ 

HWND hwnd; 

/* list the current application found in each. */ 

! **★★★*★★★★★★★**★***★**★★*★★★***★*★*★*★*★★★★★★★★*★*★★* i 

/* First instance must register a class. */ 

linclude <windows.h> 

if (! hinsPrev) 

{ 

linclude <windowsx.h> 

WNDCLASS wcs; 

linclude "dosname.h" 

Idefine wGetCallback 0x1684 /* Get VxD API. */ 

wcs.style = CS_HREDRAW | CSVREDRAW; 
wcs.lpfnWndProc = DosListWndProc; 

Idefine szApp "DosList" /* Class name. */ 

wcs.cbClsExtra * 0; 

Idefine cbBuf 129 /* Generic buffer size. *7 

wcs.cbWndExtra = 0; 

Idefine ibVM OxOOfc /* VM global in WinOldApp. */ 

wcs.hlnstance = hinsThis; 

typedef DWORD (CALLBACK * LPFN VXD API)(VOID); 

wcs.hlcon « NULL; 

wcs.hCursor = LoadCursor(NULL, IDC ARROW); 

LRESULT CALLBACK DosListWndProc(HWND, UINT, 

wcs.hbrBackground = (HBRUSH)(C0L0R_WIND0W + 1); 
wcs.lpszMenuName ■= szApp; 

WPARAM, LPARAM) ; 

wcs.lpszClassName = szApp; 

VOID CALLBACK DosNameReady(DWORD, HWND); 

if (!RegisterClass(&wcs)) 

BOOL FRegisterApp(VOID); 

return FALSE; 

VOID GetDosName(HWND, HWND); 

} 

BOOL CALLBACK IsWinOldApTask(HTASK) ; 

LPFN VXD API lpfn; 

/* Create the main window. */ 
if (!(hwnd * CreateWindow(szApp, szApp, 

char szBuf[cbBuf] ; 

WS OVERLAPPEDWINDOW, 

HGLOBAL hgblLocked; 

CW USEDEFAULT, CW USEDEFAULT, 

int PASCAL 

GetSystemMetrics(SM CXSCREEN) / 2, 

GetSystemMetrics(SM CYSCREEN) / 8, 

WinMainfHINSTANCE hinsThis, HINSTANCE hinsPrev, 

NULL, NULL, hinsThis, NULL))) 

LPSTR lszCommand, int wShowWindow) 

return FALSE; 

/* -- Entry point. */ 

/* Register with the VxD. */ 

J ****★★*★★★**★★★★★★**★★★★*★***★★★★★★★★*★★★★*★★★★★*★*★* j 

if (IFRegisterAppO) 
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to the system VM so that the data can be copied back to the 
client's buffer there. The path is copied to a local buffer since 
the system VM's LDT is not accessible from the DOS VM. 


executable path. If the bytes are not found, then no applica¬ 
tion is running and control bypasses the next bit of code, 
which copies the application's executable path to the internal 
buffer, rgchPath. The procedure then schedules a switch back 


Listing 5 continued 


ReleaseCaptureO; 
GetCursorPos(&pt); 
hwndPick » WindowFromPoint(pt); 
if (IsWinOldApTask(GetWindowTaskf 
hwndPick))) 

GetDosName(hwnd, hwndPick); 

} 

break; 

} 


return FALSE; 

ShowWindow(hwnd, wShowWindow); 

while (GetMessagef&msg, NULL, 0, 0)) 

{ 

TranslateMessage(&msg); 
DispatchMessage(&msg); 

} 


return TRUE; 
) 


return DefWindowProcfhwnd, wm, wParam, IParam); 

) 


LRESULT CALLBACK 

DosListWndProc(HWND hwnd, UINT wm, WPARAM wParam, 

LPARAM IParam) 

j★*★★*****★*★★★★★**★*★***★★★★★★******★★*★**★*★***★***★j 

/* -- Main window procedure. */ 

j ***★*★★*★*★*★*★★*★★********★★★********★★★*★★*★***★★**/ 

( 

static DWORD vm; 

switch (wm) 

( 

default: 

break; 

case WM_DESTR0Y: 
if (hgblLocked) 

GlobalPageUnlock(hgblLocked); 
PostQuitMessage(O); 
break; 

case WMJJSER: 

if (hgblLocked) 

( 

GlobalPageUnlock(hgblLocked); 
hgblLocked = NULL; 

) 

vm = IParam; 

InvalidateRect(hwnd, NULL, TRUE); 
break; 

case WM_PAINT: 

f 

char szOut[cbBuf *2 + 1]; 

PAINTSTRUCT wps; 

BeginPaint(hwnd, &wps); 
wsprintf(szOut, "VM %1x: %s\ 
vm, (LPSTR)szBuf); 

TextOut(wps.hdc, 0, 0, szOut, lstrlen(szOut)); 
EndPaint(hwnd, &wps); 

) 

return TRUE; 

case WM_LBUTT0ND0WN: 

SetCapture(hwnd); 
break; 

case WM_LBUTT0NUP: 

if (GetCaptureO «■ hwnd) 

( 

HWND hwndPick; 

POINT pt; 


VOID 

GetDosName(HWND hwndNotify, HWND hwndDOS) 

y***************************************************** j 

/* -- Ask the dosname VxD for the name of the APP in */ 

/* the VM given by the WinOldAp window. */ 

/* -- hwndNotify : Window to notify when ready. */ 

/* -- hwndDOS : WinOldAp window. */ 

j★★**★**★★**★*★*★*****★***★★***★**★**★★********★★*★★**j 
{ 

UINT uwl, uw2, uw3; /* General purpose. */ 

DWORD vm; 

/* Comment in vpostd sample says we have to do */ 



TM 


FullShot 

The Complete Image Capture 
Program for Microsoft® Windows™ 

FullShot is perfect for images you want to 
include in manuals, interface design, training 
handouts, presentations, or marketing materials. 
Q Capture images using hotkeys or the FullShot icon 
Q Choose hotkeys interactively (see below) 

Q Capture a full screen or any part of a screen 
Q Capture windows in many different ways 
Q Capture black-and-white, 16-color, and 256-color images 
Q Translate color images to gray patterns or black & white 
Q Resize, scale, flip, rotate, and crop images 
Q Export to and import from BMP, TIFF, PCX, and CLP 
Q Support all Windows graphics cards and printers 
Q Print in color, gray pattern, or black-and-white 
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XL 
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INBIT and FullShot are trademarks of INBIT. Microsoft Windows is a trademark of Microsoft. 
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The last callback, NotifyClient, tests to see if anything 
was copied to rgchPath, and if so, copies the contents to the 
buffer supplied by the client. It prepares to call the client’s 
callback by once again entering a nested execution block. It 
invokes the VMM service Simulate_Push to build a stack- 
based parameter list for the callback, then uses the services 
Simulate_Far_Call and Resume_Exec to set up the call to the 
callback and actually cause it to occur. Finally, NotifyClient 
sets selClient to 0 to guard against any attempt to re- 
entrantly call the VxD, since DosNameTest checks the global 
and bags out if it is not dear. 

Listings 2, 3, and 4 are the other files required to imple¬ 
ment the VxD. Listing 2, the header file, defines the api con¬ 
stants for use by the client application; Listing 3 is the linear 
linker definition file for the VxD; and Listing 4 is the makefile 
for both the VxD and DosList, a sample windows application 
that demonstrates how to use the beast. The VxD needs to be 
listed in the [386enh] section of system.ini with the line: 
device=dosname.386. 


A Sample Application 

DosList is a simple windows application with a rather 
hokey user interface. The user clicks down in the client area 
of the applications window, then drags over to a windowed 
DOS application or MS-DOS icon and releases the mouse. The 
VM handle and the name of the currently executing DOS ap¬ 
plication then display in the client area. DosList is imple¬ 
mented with Listing 5, the C source code; Listing 6, an empty 
resource file; and Listing 7, the linker's module definition File. 

UinMainf) is the usual boring routine that registers a class 
for the application's main window, creates the window, then 
enters a message loop until the UM_QUIT message is received. 
The only extra thing it does is to call FRegisterApp(). 
FRegisterAppO gets the protected-mode API interface to the 
Dos Name VxD using the service 0x1684 of the multiplex inter¬ 
rupt, 0x2f. If this succeeds (meaning DosName was successfully 
loaded from the system.ini specification at Windows' in¬ 
itialization time), the version number is obtained to make sure 
it is the expected 0x0100. If the version number is correct, the 


Listing 5 continued 


/* this. */ 

_asra mov hgblLocked, cs; 

G1obalPageLock(hgblLocked); 

/* Get VH handle out of WinOldApp's DS! */ 
vm ■ *(LPDWORD)MAKELP(GetWindowInstance(hwndDOS), 
ibVM); 

uwl = HIWORD(vm); 
uw2 = LOWORD(vm); 
uw3 = (UINT)szBuf; 

IstrcpyfszBuf, "No app detected"); 

/* Call to VxD to get current DOS app name. */ 

/* cx:bx : VM handle. */ 

/* ds:dx : Buffer to receive DOS app name. */ 

/* si : Window to notify. */ 

/* ax : Get-path-name prot-mode API id. */ 

_asm 

{ 

mov cx, uwl 

mov bx, uw2 

mov dx, uw3 

mov si, hwndNotify 

mov ax, apiDosName 

) 

(*lpfn) (); 

} 

VOID CALLBACK 

DosNameReady(DWORD vm, HWND hwnd) 


/* -- Callback from VxD. */ 
/* -- Called when the requested VM path has been */ 
/* obtained. */ 
/* — Called on stack of VxD with unknown DS! */ 
/* -- vm : Handle of VM containing DOS app. */ 
/* -- hwnd ; Window to notify. */ 


I*★*★★★★*★★*★★**★***★***★*★★*★★★**★★★★*★★★★★★*★*★★*★**i 

{ 

PostMessage(hwnd, WM_USER, 0, vm); 

} 


BOOL 

FRegisterApp(VOID) 

/★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★A********************** j 

/* -- Register callback with VxD. */ 

/* -- Return false if VxD not detected or wrong */ 
/* version. */ 

j*★★**★***★★★★★★★*********★***★*****★★★****★***★**★★*★j 
{ 

WORD sb, ib; 

/* Get the address of the DosName VxD's protect */ 
/* mode API dispatcher. */ 

_asm 

{ 

xor di, di 

mov es, di 

mov ax, wGetCallback 

mov bx, wDosNameDeviceld 

int 0x2f 

mov ib, di 

mov sb, es 

} 

if (I(Ipfn = (LPFN_VXD_API)MAKELONG(ib, sb))) 
return FALSE; 

/* Make sure expected version is installed. */ 

_asm mov ax, apiGetVersion; 
if ((WORD)(*1pfn)() < wDosNameVersion) 
return FALSE; 

sb = HIWORD(DosNameReady); 
ib = LOWORD(DosNameReady); 

_asm 

{ 

mov dx, sb 

mov bx, ib 

mov ax, apiRegister 

) 

(*1pfn)(); 
return TRUE; 

) 

/* End of File *! 
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address of the callback notification routine, DosNameReady () is 
registered with VxD via the apiRegister service. 

DosListUndProcf) looks for mouse-up and mouse-down 
events. On a mouse-down it captures the cursor so that a 
mouse-up can be received from outside the window. If you 
receive a mouse-up while the mouse is captured, you know 
the user is dragging and you can use UindowFromPointf) to 
see which window was under the mouse when the user 
released the left button. The undocumented function IsUin- 
OldApTask() (described in Schulman, Maxey, and Pietrek’s Un¬ 
documented Windows) is used to determine if the window is 
for a DOS session. Despite being undocumented, IsUinOldAp- 
Task() is probably safer to use than GetModuleFileName (), 
which must rely on the name of the executable as it resides 
on disk. 

If the window is for a DOS session, GetDosNamef) is called. 
GetDosNamef) calls Global Page Lock () for the code segment 
containing the DosNameReady () callback. A note in the sample 
VPOSTD VxD supplied with the DDK, "need to guarantee that 
phCallBack() is in FIXED (page-locked) segment," seems to in¬ 
dicate that this is necessary. I am not sure why this is a re¬ 
quirement, since the callback is made through a selectonoffset 
address which gets mapped by hardware to a physical (page) 
address. Perhaps there is a need to prevent the paging VxD 
from relocating the callback once the Resume_Execution 
VMM service has been called. GetDosName() gets the VM 
handle from offset 0x00fc in UinOldAp’s DS and initializes the 
registers used to pass the VM handle, notification window, 
and path buffer to the protected-mode API function before 
calling it. The buffer is initialized with the string “No app 
detected” before requesting the apiDosName service. The VxD 
will not copy into the buffer if no task is running, so by the 
time DosNameReady () is called, the buffer will contain either 


Listing 6 doslist.rc 


/* dostlist.rc */ 

/* — DosList (empty) resource file. */ 

j*****************************************************i 


Listing 7 doslistdef 



;; dosllst.def ;; 

;; -- Linker definition file for the Dos Lister app. ;; 

NAME 

DosList 

DESCRIPTION 

’DosList Demo Application 1 

EXETYPE 

WINDOWS 

STUB 

’WINSTUB.EXE’ 

CODE 

PRELOAD MOVEABLE DISCARDABLE 

DATA 

PRELOAD MOVEABLE MULTIPLE 

HEAPSIZE 

1024 

STACKSIZE 

EXPORTS 

10240 

DosListWndProc @1 

IMPORTS 


IsWin01dApTask=KERNEL.158 


the name of the executing DOS task or the “No app detected" 
string. DosNameReady () posts a UMJJSER to the main window. 
Upon receipt of the UM_USER, DosListUndProcf) unlocks the 
code segment and formats a local static string to be displayed 
when the window is painted. 

If you require extraction of the DOS application name to be 
synchronous, you can create a routine that calls GetDosNamef) 
and enters a message loop until UM_USER is received by the 
main window procedure. At this point the string has been ac¬ 
quired and your routine can return. 

Conclusion 

The VxD presented here covers some of the basic con¬ 
cepts, such as scheduling a VM switch, simulating a real-mode 
interrupt, and calling a protected-mode function. Writing even 
a simple VxD is a tough job. It is an exercise in trial and error. 
Having a debugger designed for the task, such as Soft-lce/W 
helps considerably, but even so, be prepared for heavy use of 
the reboot switch, d 
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New Products 

Industry-Related News & Announcements 


Symantec Ships Multiscope v2.0 

The MultiScope debuggers are a suite of tools for debug¬ 
ging DOS and Windows programs compiled with Borland and 
Microsoft C++ compilers. Debuggers in the suite handle both 
DOS and Windows debugging, both local and remote (via a 
serial port or network, for example) debugging, and both in¬ 
teractive and post-mortem debugging. The Windows debug¬ 
gers offer an MDI Windows interface and can display data 
structures graphically in a window. 

The new versions of the MultiScope Debuggers now sup¬ 
port Borland C++, Microsoft C v6.0, and Microsoft C/C++ v7.0. 
New C++ features include a “point-and-shoot" collapse and 


expand C++ class hierarchy browser, C++ object browsing, 
automatic C++ object mapping for all C++ inheritance types, 
complete C++ expression evaluation, and object-oriented 
breakpoints directly on object methods. 

MultiScope Debuggers for Windows costs $379. Multi- 
Scope Debuggers for DOS costs $179. MultiScope was ac¬ 
quired by Symantec in June. For more information, contact 
Symantec Corporation, 10201 Torre Avenue, Cupertino, CA 
95014-2132, (408) 253-9600; FAX (408) 253-4092; Telex 
9103808778. 


SourceSafe Provides Windows Project Control 


SourceSafe is a project-oriented version control system 
from One Tree Software, available for both Windows and 
DOS. Besides standard source-code control features, Source¬ 
Safe offers the ability to operate at the project level rather 
than the file level. SourceSafe can track file-project relation¬ 
ships, such as a single source file that is used in more than 
one project 

SourceSafe v2.0 for Windows and SourceSafe v2.0 for DOS 
each cost $295 for one user, $1,195 for five users, $1,995 for 


ten users, $3,795 for twenty users, and $8,145 for fifty users. 
A combination package containing both products costs $445 
for one user, $1,795 for Five users, $3,095 for ten users, 

$5,795 for twenty users, and $12,245 for fifty users. For more 
information, contact One Tree Software, P.O. Box 11639, 
Raleigh, NC 27604, (800) 397-2323 or (919) 821-2300; FAX 
(919)821-5222. 


ThunderNET Provides NetBIOS Interface for Windows 


ThunderNET is a Windows DLL that provides an easier in¬ 
terface to all the functions of NetBIOS. The library offers 
named, C-callable functions for NetBIOS operations in both 
pended and non-pended flavors. ThunderNET transparently 
handles allocating and freeing Network Control Blocks, and 
signals completion of non-pended operations with a Win¬ 
dows message, removing the need to write post routines. 
Programmers can attach extra bytes to any network opera¬ 
tion, similar to class or window extra bytes, to separate one 


operation from another in a generic completion handler. 
ThunderNET is usable by up to 12 simultaneous applications 
or instances. 

ThunderNET costs $195 for a single programmer license, 
$495 for a full development site license, and requires no end- 
user royalties. Source code costs an additional $500. For 
more information, contact Rolling Thunder Computing, 20 
Hilltop Terrace, Woburn, MA 01801, (617) 938-4326. 

continued on page 74 
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Add Options to Your 
Windows Message Boxes 

Steven Palmer 

If you have used Microsoft Excel or Word, you have seen the extra “Help” button 
on their message boxes. Clicking this button is akin to pressing FI while the mes¬ 
sage box is displayed — it brings up the Excel or Word online help topic for the 
message box. This convention, which is making its way into all other Microsoft ap¬ 
plications, is part of the Microsoft User Interface guidelines aimed at making Win¬ 
dows programs visually consistent. 

However, the standard API function MessageBoxf) has no provision for a “Help” 
button, or indeed, for extending the available range of options. Therefore it seems 
that Word and Excel eschew MessageBoxf) in favor of a more flexible, homespun 
variant. This article describes how I implemented my version of this extended 
MessageBoxf). I also examine an area of Windows programming rarely touched on — 
creating dynamic dialog boxes. 

The Application Interface 

Because I wanted to add the extended MessageBox() (which I named Message- 
BoxEx()) to my existing Windows applications, I decided to make it as compatible 
with the standard MessageBox() function as possible. The first four parameters of 
MessageBoxEx() are the same as for MessageBox(). The remaining two parameters 
implement the extended style bits and an optional callback address. The prototype 
for MessageBoxEx() looks like this: 

int FAR PASCAL MessageBoxEx( HWND hwnd, LPSTR lpcszStr, 

LPSTR lpcszTitle, unsigned fuStyle, unsigned fuStyleEx, 

WNDPROC lpfMsgProc ); 

The first extra parameter, fuStyleEx, lets you define new styles in addition to 
those passed in the standard fuStyle parameter. This is necessary because all the 
bits of fuStyle are already defined by Microsoft. At the moment, I have used only 

two bits of fuStyleEx: MB_EX_HELP, which specifies 
whether or not the extended message box has a "Help” 
button, and MB_EX_DEFBUTT0N4, which establishes that 
the “Help” button is the default button if it is the fourth 
button in the message box. 


=m= 

Microsoft C/C++ v7.0 
Borland C++ v3.1 


Windows 3.0/3.1 


Steven Palmer is the Chief Software Engineer for LJ Technical Systems Ltd, a British 
firm developing Computer-Aided Training systems for electronics and microelectronics 
students. He mag be contacted on CompuServe: 100031,504. 
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Listing 1 msgboxex.c - Extended Message Box Function 


#include <windows.h> 

♦include "msgboxex.h" 

♦define MSGBOXEX_SPACING 
#define MSGBOXEX_BUTTONWIDTH 
♦define MSGBOXEX~BUTTONHEIGHT 
♦define MSGBOXEX_BUTTONSPACING 
♦define MSGBOXEX_BOTTOMMARGIN 
#define MSGBOX EX_MAXWIDTH 

♦define MSGBOXEX_HINHEIGHT 

♦define IDD_ICON 

typedef struct { 
long dtStyle; 

BYTE dtltemCount; 

int dtX; 

int dtY; 

int dtCX; 

int dtCY; 

cher dtMenuName[ 1 ]; 
char dtClassName[ 1 ]; 

char dtCaptionText[ 1 ]; 

) DLGTEMPLATE; 

typedef struct { 
int dtilX; 

int dtilY; 

int dtilCX; 

int dtilCY; 

int dtillDj 

long dtilStyle; 

char dtilClass[ 1 ] ; 

char dtilText[ 1 ]; 

BYTE dtilInfo; 

) DLGITEMTEMPLATE; 

static int Add01gltem( HANDLE, int, int, int, int, 

int, int, long, LPSTR, LPSTR ); 
static int AddButtonItem( HANDLE, int, int, int, 

int, LPSTR ); 

WNDPROC lpfnHookProc = NULL; /* MessageBox hook 

procedure */ 

HICON hlcon; /* Handle of icon */ 

int nDefButton; /* Default button */ 

BOOL _export FAR PASCAL MsgBoxDlgProc( HWND, 

unsigned, WORD, LONG ); 

LONG _export FAR PASCAL IconProc( HWND, unsigned, 

WORD, LONG }; 

char * szOK = "OK"; 
char * szCancel = "Cancel"; 
char * szlgnore = "Signore"; 
char * szRetry = "ARetry"; 
char * szAbort = "AAbort"; 
char * szHelp ■ "AHelp"; 
char * szYes * "AYes"; 
char * szNo * "ANo"; 

/* HessageBoxEx */ 

int FAR PASCAL MessageBoxEx( 

HWND hwnd, LPSTR lpcszStr, 

LPSTR lpcszTitle, unsigned fuStyle, 
unsigned fuStyleEx, WNDPROC lpfMsgProc ) 

{ 

DLGTEMPLATE FAR * IpDlgTmp; 

HINSTANCE hlnst; 

FARPROC lpMsgBoxDlgProc; 

HGLOBAL hDlgTmp; 

int nRetCode, cwButtonRow, cbTemplate, cxMsgBox, cyMsgBox; 
int cltems, dxLeft, x, y; 

HOC hdc; 


RECT rc; 

if( fuStyle == (MB_ICONHAND|MB_SYSTEMMODAL) AA 
fuStyleEx ** 0 ) 

return( MessageBox( hwnd, lpcszStr, lpcszTitle, 
fuStyle ) ); 

hdc « CreateDC( "DISPLAY", NULL, NULL, NULL ); 
SelectObject( hdc, GetStockObject( SYSTEMFONT ) ); 
SetRect( ire, 0, 0, MSGBOXEX_MAXWIDTH, 0 ); 

DrawText( hdc, lpcszStr, -1, Src, DT_LEFT| 

DT_NOPREFIX|DT_WORDBREAK|DT_CALCRECT ); 
rc.right += 10; 

DeleteDC( hdc ); 

if( llpcszTitle ) 

lpcszTitle - "Error"; 

cyMsgBox = rc.bottom + ( MSGBOXEX_SPACING * 2 ); 
cxMsgBox - rc.right + ( MSGBOXEX_SPACING * 2 ); 
dxLeft - MSGBOXEX SPACING; 
hlcon = NULL; 

cbTemplate = sizeof(DLGTEMPLATE) + 1strlen(lpcszTitle); 
hDlgTmp = GlobalAlloc( GHND, cbTemplate ); 
if( !hDlgTmp ) 
return( 0 ); 

IpDlgTmp = (DLGTEMPLATE FAR *)GlobalLock( hDlgTmp ); 
if( IlpDIgTmp ) ( 

Global Free( hDlgTmp ); 
return( 0 ); 

1 

lpDlgTmp->dtStyle = DS_MODALFRAME | WS POPUP | 

WS_CAPTION | _ WS_SYSMENU; 

lpDlgTmp->dtItemCount * 0; 

lpDlgTmp->dtX = 0; 

lpDlgTmp->dtY - 0; 

lpDlgTmp->dtMenuName[ 0 ] = '\0 1 ; 

lpDlgTmp->dtClassName[ 0 ] = 1 \0 1 ; 

lstrcpy( lpDlgTmp->dtCaptionText, lpcszTitle ); 

GlobalUnlock( hDlgTmp ); 

if( fuStyle i MB_SYSTEMMODAL ) 

lpDlgTmp->dtStyle |= DSSYSMODAL; 

if( cyMsgBox < MSGBOXEXMINHEIGHT ) 
cyMsgBox = MSGBOXEX_MINHEIGHT; 

if( fuStyle i MBICONMASK ) ( 
int cxlcon; 
int cylcon; 

LPSTR 1plcon; 

switch( fuStyle i MB_ICONMASK ) { 
case MB_ICONEXCLAMATION: 

1plcon = (LPSTR)IDI_EXCLAMATION; 
break; 

case MB_ICONHAND: 

lplcon = (LPSTR)IDI_HAND; 
break; 

case MB_ICONQUESTION: 

lplcon = (LPSTR)IDI_QUESTION; 
break; 

case MBJCONASTERISK: 

lplcon = (LPSTR)IDI_ASTERISK; 
break; 

1 

hlcon = LoadIcon( NULL, lplcon ); 

cxlcon = GetSystemMetrics( SM_CXIC0N ); 
cylcon = GetSystemMetrics( SM_CYIC0N ); 
dxLeft += MSGBOXEX_SPACING + cxlcon; 
cxMsgBox += dxLeft; 
y * ( cyMsgBox - cylcon ) / 2; 


18 

58 

28 

16 

10 

240 

70 

0xA90 
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The second extra parameter, IpfMsgProc, is the procedure 
instance address of a callback function defined by the calling 
application. If this address is not NULL, then MessageBoxEx() 
calls the callback function before the dialog procedure for the 
message box begins processing. If the MB_EX_HELP bit is set in 
fuStyleEx, then the caller must include a callback function, as 
it uses the UM_COMMAND message to detect when the “Help” 
button is pressed. However, the implementation is far more 
versatile than this, because the callback function actually 
receives every single message passed to the message box 
dialog procedure. It can, for example, trap the UM_CTLCOLOR 
message and paint the message box background a different 
colour. 

The Implementation 

My implementation of MessageBoxEx() is shown in Listing 
1 i/nsgboxex.c). The header file that defines the interface to 
the new function is in Listing 2 (fnsgboxex.h). 

Crafting a replacement for MessageBox() is not so 
straightforward. The standard message box is an ordinary 

Listing 1 continued 


cbTemplate +* Add01gltem( hDlgTmp, cbTemplate, 
MSGBOXEX_SPACING, y, cxlcon, cylcon, 
IDDJCON, WS_CHILD|SS_ICON,"static", "" ); 

) 

y « ( cyMsgBox - rc.bottom ) / 2; 
cbTemplate += AddDlgItem( hDlgTmp, cbTemplate, 
dxLeft, y, rc.right, rc.bottom, -1, 
WS_CHILD|SS_LEFT,“static", IpcszStr ); 
switchf fuStyle & MBTYPEMASK ) ( 


case 

MB OK: 

cltems 

= i; 

break; 


case 

MB - OKCANCEL: 

cltems 

- 2; 

break; 


case 

MB YESNO: 

cltems 

- 2; 

break; 

■ 

case 

MB YESNOCANCEL: 

cltems 

* 3; 

break; 


case 

MB ABORTRETRYIGNORE: 

cltems 

* 3; 

break; 


case 

MB RETRYCANCEL: 

cltems 

* 2; 

break; 



if( fuStyleEx & MB_EX_HELP ) 

++cltems; 

cwButtonRow = MSGBOX£X_BUTTONWIDTH * cltems + 

( MSGBOXEXBUTTONSPACING * ( cltems - 1 ) ); 
if( cwButtonRow > ( cxMsgBox - dxLeft ) ) 
cxMsgBox = dxLeft + cwButtonRow + 

MSGBOXEX_BUTTONSPACING * 2; 
lpfnHookProc * IpfMsgProc; 
nDefButton = 1; 

switch( fuStyle & MBDEFMASK ) { 

case MB_DEFBUTT0N1: nDefButton = 1; break; 

case MB_DEFBUTT0N2: nDefButton = 2; break; 

case MB_DEFBUTT0N3: nDefButton = 3; break; 

1 

if( fuStyleEx & MB_EX_DEFBUTT0N4 ) 
nDefButton « 4; 

x = ( cxMsgBox - cwButtonRow ) / 2; 
switch( fuStyle & MB_TYPEMASK ) { 
case MB_OK: 

cbTemplate += AddButtonItem( hDlgTmp, 

cbTemplate, x, cyMsgBox, IDOK, szOK ); 

break; 

case MB_OKCANCEL: 

cbTemplate += AddButtonItem( hDlgTmp, 

cbTemplate, x, cyMsgBox, IDOK, szOK ); 
CbTemplate += AddButtonltemf hDlgTmp, 

cbTemplate, X += MSGBOXEX_BUTTONSPACING + 
MSGBOXEXJUTTONWIDTH, cyMsgBox, IDCANCEL, 
szCancel ); 

break; 
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Listing 1 continued 


case MB YESNO: 

int dtillD, LPSTR IpszStr ) 

cbTemplate += AddButtonItem( hDlgTmp, 

{ 

cbTemplate, x, cyMsgBox, IDYES, szYes ); 
cbTemplate +* AddButtonItem( hDlgTmp, 

long 1 Style; 

cbTemplate, x += MSGBOXEX BUTTONSPACING + 

1 Style = WS CHILD | WS TABSTOP | 

MSGBOXEX BUTTONWIDTH, cyMsgBox, IDNO, 

( —nDefButton ? BS PUSHBUTTON : 

szNo }; 

BS DEFPUSHBUTTON ); 

break; 

return( AddDlgItem( hDlgTmp, cbTemplate, x, y. 

case MB YESNOCANCEL: 

MSGBOXEX BUTTONWIDTH, 

CbTemplate += AddButtonItem( hDlgTmp, 

MSGBOXEX BUTTONHEIGHT, 

CbTemplate, x, cyMsgBox, IDYES, szYes ); 

dtillD, IStyle, "button", IpszStr ) ); 

cbTemplate +» AddButtonItem( hDlgTmp, 

cbTemplate, x += MSGBOXEX BUTTONSPACING + 
MSGBOXEX BUTTONWIDTH, cyMsgBox, IDNO, szNo ); 

1 

cbTemplate +* AddButtonItem( hDlgTmp, 

BOOL FAR PASCAL MsgBoxDlgProc( HWND hwnd, 

CbTemplate, x += MSGBOXEX BUTTONSPACING + 

unsigned message, WORD wParam, LONG IParam ) 

MSGBOXEX BUTTONWIDTH, cyMsgBox, IDCANCEL, 

{ 

szCancel ); 

if( IpfnHookProc ) 

break; 

{ 

case MB_ABORTRETRYIGNORE: 

cbTemplate += AddButtonItem( hDlgTmp, 

LONG 1 Result; 

cbTemplate, x, cyMsgBox, IDABORT, 

IResult * (*lpfnHookProc)( hwnd, message, 

szAbort ); 

wParam, IParam ); 

cbTemplate += AddButtonItem( hDlgTmp, 

if( IResult && message != WM INITDIALOG ) 

CbTemplate, x += MSGBOXEX BUTTONSPACING + 

return ( (BOOL)IResult ); 

MSGBOXEX BUTTONWIDTH, cyMsgBox, IDRETRY, 

) 

szRetry ) ; 

switch ( message ) 

cbTemplate += AddButtonItem( hDlgTmp, 

( 

CbTemplate, x += MSGBOXEX BUTTONSPACING + 

case WM INITDIALOG: { 

MSGBOXEX BUTTONWIDTH, cyMsgBox, IDIGNORE, 

RECT rc; 

szlgnore ); 

if( hlcon ) { 

break; 

HWND hwndIcon; 

case MB RETRYCANCEL: 

hwndlcon = GetDlgItem( hwnd, IDD ICON ); 

cbTemplate += AddButtonItem( hDlgTmp, 

SetWindowLong( hwndlcon, GWL WNDPROC, 

cbTemplate, x, cyMsgBox, IDRETRY, 

(LONG)IconProc ); 

szRetry ); 

) 

cbTemplate += AddButtonItem( hDlgTmp, 

GetWindowRect( hwnd, &rc ); 

cbTemplate, x += MSGBOXEX BUTTONSPACING + 

SetWindowPos( hwnd, NULL, 

MSGBOXEX BUTTONWIDTH, cyMsgBox, 

( GetSystemMetrics( SM CXSCREEN ) - 

IDCANCEL, szCancel ); 

( rc.right - rc.left ) ) / 2, 

break; 

( GetSystemMetrics( SM CYSCREEN ) - 

) 

( rc.bottom - rc.top ) ) / 3, 

if( fuStyleEx » MB EX HELP ) 

0, 0, SWP NOSIZE I SWP NOACTIVATE ); 

cbTemplate += AddButtonItem( hDlgTmp, 

return( TRUE ); 

cbTemplate, x += MSGBOXEX BUTTONSPACING + 

) 

MSGBOXEX BUTTONWIDTH, cyMsgBox, IDEXHELP, 

case WM COMMAND: 

szHelp ); 

if( wParam !» IDEXHELP ) 

lpDlgTmp = (DLGTEMPLATE PAR *)GlobalLock( hDlgTmp ); 

EndDialog( hwnd, wParam ); 

if( UpDlgTmp ) { 

break; 

GlobalFree( hDlgTmp ); 

default: 

return( 0 ); 

) 

cyMsgBox += MSGBOXEX BOTTOMMARGIN + 

return( FALSE ); 

i 

/ 

return( FALSE ); 

MSGBOXEX_BUTTONHEIGHT; 
cyMsgBox * ( cyMsgBox * 8 ) / 

HIWORD( GetDialogBaseUnits() ); 

) 

cxMsgBox = ( cxMsgBox * 4 ) / 

LONG FAR PASCAL IconProc( HWND hwnd, unsigned message. 

LOWORD( GetDialogBaseUnits() ); 

WORD wParam, LONG IParam ) 

lpDlgTmp->dtCX = cxMsgBox; 

( 

lpDlgTmp->dtCY = cyMsgBox; 

if( message == WM PAINT ) ( 

GlobalUnlock( hDlgTmp ); 

hlnst = (HINSTANCE)GetWindowWord( hwnd, GWW HINSTANCE ); 

PAINTSTRUCT ps; 

HDC hdc; 

lpMsgBoxDlgProc = MakeProcInstance( 

hdc = BeginPaint( hwnd, &ps ); 

(FARPROC)MsgBoxDlgProc, 

DrawIcon( hdc, 0, 0, hlcon ); 

hlnst ); 

EndPaint( hwnd, &ps ); 

nRetCode = DialogBoxIndirect( hlnst, hDlgTmp, 

) 

hwnd, (DLGPROC)lpMsgBoxDlgProc ); 

return( FALSE ); 

FreeProcInstance( lpMsgBoxDlgProc ); 

GlobalFree( hDlgTmp ); 

) 

return( nRetCode ); 

static int AddDlgItem( HANDLE hDlgTmp, int cbTemplate, 

1 

int dtilX, int dtilY, int dtilCX, int dtilCY, 
int dtillD, long dtilStyle, LPSTR lpdtilClass, 

static int AddButtonItem( HANDLE hDlgTmp, 
int cbTemplate, int x, int y. 

LPSTR lpdtilText ) 
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dialog box, but the controls displayed within the dialog, their 
position, and the size of the dialog box itself, all vary depend¬ 
ing on the message box style and the length of the message. 
Using predefined dialog templates for all the possible variants 
would not only be a waste of space, but would be impractical 
to maintain. Clearly what is needed is a way to construct a 
dialog box on the fly. 

Luckily, Windows includes functions that allow you to cre¬ 
ate a dialog box dynamically, as opposed to using one 
prepared by the dialog editor. A dialog is defined by a single 
DLGTEMPLATE structure followed by an array of DLGITEM- 
TEMPLATE structures, one for each control in the dialog. 
Passing a pointer to the DLGTEMPLATE structure to 


Listing 1 continued 


f 

DLGTEMPLATE FAR * lpDlgTmp; 

DLGITEMTEMPLATE FAR * lpDlgltemTmp; 
int cbltem; 

LPSTR lpstr; 

cbltem = sizeof( DLGITEMTEMPLATE ) + 
lstrlen( lpdtilClass ) + 
lstrlen( 1pdti1 Text ); 

hDlgTmp = GlobalReAlloc( hDlgTmp, cbTemplate + 
cbltem, GMEM_MOVEABLE ); 

lpDlgTmp = (DLGTEMPLATE FAR *)G1 obalLock( hDlgTmp ); 

++1pDl gTmp->dtItemCount; 

dtilY = ( dtilY * 8 ) / HIW0RD( GetDialogBaseUnits() ); 
dtilX = ( dtilX * 4 ) / LOWORD( GetDialogBaseUnitsQ ); 
dtilCY * ( dtilCY * 8 ) / HIWORD( GetDialogBaseUnits() ); 
dtilCX = ( dtilCX * 4 ) / LOWORD( GetDialogBaseUnitsQ ); 
lpDlgltemTmp ■= (DLGITEMTEMPLATE FAR *) ( 

(LPSTR)lpDlgTmp + cbTemplate ); 
lpDlgItemTmp->dtilX = dtilX; 
lpDlgItemTmp->dtilY ■ dtilY; 
lpDlgItemTmp->dtilCX = dtilCX; 
lpDlgItemTmp->dtilCY = dtilCY; 
lpDlgItemTmp->dtilID = dtillD; 
lpDlgItemTmp->dtilStyle = dtilStyle | WS_VISIBLE; 

/* Copy in the class name. */ 

lpstr = (LPSTR)&lpDlgItemTmp->dtilClass; 

lstrcpy( lpstr, lpdtilClass ); 

/* Copy in the item text */ 
lpstr += lstrlen( lpdtilClass ) + 1; 
lstrcpy( lpstr, lpdtilText ); 

lpstr +* lstrlen( lpdtilText ) + 1; 

*lpstr = 0; 

Global Uni ock( hDlgTmp ); 
return( cbltem ); 

} 

/* End of File */ 


Listing 2 msgboxex.h - Interface to extended 
message box function 


#define MB_EX_HELP 1 

Idefine MB_EX_DEFBUTT0N4 0x0100 

Idefine IDEXHELP 300 

int FAR PASCAL MessageBoxEx( HWND, LPSTR, LPSTR, 
unsigned, unsigned, WNDPR0C ); 

/* End of File */ 
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Figure 1 DLGTMPLATE and DLGITEMTEMPLATE Structures 

typedef struct { 



long 

dtStyle; 

/* 

Dialog style bits */ 

BYTE 

dtltemCount; 

/* 

Number of controls in the dialog */ 

int 

dtX; 

/* 

Dialog box X coordinate */ 

int 

dtY; 

/* 

Dialog box Y coordinate */ 

int 

dtCX; 

/* 

Width of dialog */ 

int 

dtCY; 

/* 

Height of dialog */ 

char 

dtMenuNamef 1 ]; 

/* 

Optional dialog menu name */ 

char 

dtClassNamef 1 ]; 

/* 

Optional dialog class name */ 

char 

dtCaptionTextf 1 ]; 

/* 

Optional dialog caption */ 

} DLGTEMPLATE: 



typedef struct ( 



int 

dtilX; 

/* 

X coordinate of control */ 

int 

dtilY; 

/* 

Y coordinate of control */ 

int 

dtilCX; 

/* 

Width of control */ 

int 

dtilCY; 

/* 

Height of control */ 

int 

dtillD; 

/* 

Control identifier */ 

long 

dtilStyle; 

/* 

Style bits for control window */ 

char 

dtllClassf 1 ]: 

/* 

Control class name */ 

char 

dtilTextf 1 ]; 

/* 

Optional control caption */ 

BYTE 

dtilInfo; 

/* 

Extra information byte */ 

} DLGITEMTEMPLATE: 




DialogBoxIndirect() causes Windows to display a standard 
dialog box and fill it with the controls parsed from the array. 

The DLGTEMPLATE and DLGITEMTEMPLATE structures are 
shown in Figure 1. Neither of these appears in windows, h-, 
strictly speaking, the structures cannot be described with 


these struct definitions, since the 
strings in the structure are all variable 
length. 

The DLGTEMPLATE structure defines 
the appearance of the dialog box, its 
size and position on the screen, and 
any menu or caption. The size and posi¬ 
tion are in dialog units, not pixels. To 
convert pixels to dialog units, I use Get- 
DialogBaseUnit(). 

Each control in the dialog is defined 
by a single DLGITEMTEMPLATE structure. 
The structure defines the control's size 
and position (again in dialog units), its 
ID, class, and style, and an optional cap¬ 
tion. All this information normally ap¬ 
pears after the CONTROL keyword in a 
. rc file definition of a dialog box. 

MessageBoxEx() first computes the 
height and width of the message text 
based on the system font. DrawText() 
has a useful option that allows it to 
compute the dimensions of the text as 
a rectangle. However, I found that the 
right-hand edge of this rectangle was usually too short —so I 
manually extend it by 10 pixels to compensate. 

Given the dimensions of the text, it is fairly simple to com¬ 
pute the placement of the other controls within the message 
box. If an icon is specified, I add the width of the icon, plus 
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some spacing, to the overall width of the message box. Then I 
compute the width of all the buttons, together with any inter¬ 
button spacing. If this value is greater than the width of the 
text plus any icon, then I use it as the message box width 
instead. 

As well as computing the positions of the text, icon, and 
buttons, the code has to handle nonvisual style bits in fu- 
Style. By default, the first button is always the default button 
and is activated if the user presses Enter. However, the caller 
can designate any other button as the default by specifying 
MB_DEFBUTTONx, where x is the button number. To make the 
“Help” button the default, the MB_EX_DEFBUTT0N4 bit must be 
set in fuStyleEx. 

Furthermore, the user can force the message box to be 
application-, system-, or task-modal. If 
the message box is application-modal, 
the user can either switch away from 
the application (using Alt+Tab or by 
clicking on another application window) 
or switch to another instance of that 
same application. If the message box is 
task-modal, then the user can only 
switch to a different application. Finally, 
if the message box is system-modal, no 
switching is permitted at all and the 
user must respond to the message box 
by clicking one of the buttons before 
Windows will continue. My extended 
message box can be either application- 
or system-modal, but not task-modal. 

In addition to its standard message 
box, Windows has a special system- 
modal message box that is preloaded 
by user.exe and never discarded. This 
makes it ideal for reporting errors in 
situations where Windows itself is run¬ 
ning extremely low on memory and 
would be unable to load the standard 
message box resources from disk. How¬ 
ever, this message box is limited to one 
line of text, an “OK” button, and no icon. 

Because MessogeBoxEx() requires 
resources that would probably need to 
be loaded from disk, I decided to make 
an early check for this type of message 
box and use the default Windows ver¬ 
sion. 

A problem occurred when I was at¬ 
tempting to display the icons that 
MessageBoxf) supports, such as the ex¬ 
clamation point in a circle, the stop 
sign, and so on. The standard Message- 
Box () icons are taken from within the 
current video display driver, dis¬ 
play, drv, and are scaled for the screen 
resolution and color depth. You can ac¬ 
cess these icons only via LoadIcon(), 
however, and DLGITEMTEMPLATE has no 
provision for passing an icon handle. 

Under Windows 3.1, you can change 


the icon resource by passing the STM_SETICON message to the 
icon, but I wanted to make the code compatible with Win¬ 
dows 3.0. 

My solution is a kludge. I retrieve the handle of the icon 
while building the DLGITEMTEMPLATE array and save this 
globally. Then, within the UM_INITDIALOG handler, I subclass 
the icon procedure to trap UM_PAINT messages sent by Win¬ 
dows to the icon itself, and, within the WM_PAINT handler, 
manually draw the icon using Drawlconf). 

Finally, although I do not prohibit you from including a 
“Help” button in a system modal message box, you should not 
call winhelp.exe or any other application when the “Help" 
button is pressed; otherwise the results will be unpredictable. 
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Quadbase 
Systems Inc. 

790 Lucerne Drive #51 
Sunnyvale, CA 94086 
Voice: (408) 738-6989 
Fax: (408) 738-6980 



* Other trademarks appearing in this ad are trademarks of their respective companies. 


□ Request 175 on Reader Service Card □ 

Windows/DOS Developer’s Journal — Page 43 


December 1992 





































































The Callback Message Handler 

So far, MessageBoxEx() draws a standard message box, 
complete with buttons and icons. However, processing the 
“Help" button really needs to be done by the calling applica¬ 
tion. The alternative would require passing the help file name 
and context string as part of the parameters, a tactic that 
would not only make the whole function awkward, but would 
unnecessarily restrict the behavior of the Help button to call¬ 
ing winhelp.exe. By letting the calling application detect 
when the “Help" button was pressed and decide how to 
respond, MessageBoxExO is more versatile. 

This versatility is achieved by passing the procedure in¬ 
stance address of a hook function as the last parameter of 
MessageBoxEx (). When the dialog procedure for the message 
box is called, it checks if the hook address is non-zero-, if so, it 
calls the hook function, passing the message box window 
handle, message code, and parameters. If the return value 
from the hook function is non-zero, the dialog procedure as¬ 
sumes that no further processing of that message is required, 
and returns immediately. The only exception is WM_INIT- 
DIALOG, which must be handled by the dialog procedure as it 
is responsible for subclassing the icon procedure. 

To process the “Help" button, the calling application must 
supply a procedure instance address of a hook function. When 
the user presses the “Help” button, the hook function is called 


Figure 2 A MessageBoxExO Pull-Down Menu 



with the message number set to WM_COMMAND and wParam set 
to the predefined constant, IDD_HELP. The hook function can 
then respond as appropriate. 

The UM_INITDIALOG message handler of the message box 
dialog procedure also arranges the dialog so that it fits in the 
center of the screen. I prefer to place the dialog slightly higher 
than normal, as most people's default viewing area is in the 
top third of the screen rather than in the absolute middle. 

Testing 

I have written a program (included on the code disk) to 
test MessageBoxExf). As shown in Figure 2, a single pull-down 
menu allows you to put together any variation of the mes¬ 
sage box: single-line, wrapped-line or multiple-lines, with or 
without icons or a “Help” button. Note that I have used 
predefined MB_ constants as menu identifiers, which simplifies 
the test rig program. Figure 3 shows one example of the 
dialog that MessageBoxEx () generates. 

To use the test rig, choose the type of buttons and icons 
and whether or not the message box will have a “Help” but¬ 
ton. Then choose one of the three types of messages. If you 
choose a system-modal message with just the “OK" button 
and a Stop icon, the message box appears using the Windows 
system-modal display. Because this type of message box is 
longer than mine, the wrapped message will not wrap. 

Conclusion 

The Windows user interface "standard" is a moving target, 
and keeping your application up-to-date can be a daunting 
task. MessageBoxExf) lets you easily update existing applica¬ 
tions to meet this particular new user interface requirement. 

References 

Microsoft Corporation. The Windows Interface: An Applica¬ 
tion Design Guide. Redmond, WA: Microsoft Press, 1992. ISBN: 
1-55615-384-8. □ 


Figure 3 A MessageBoxExO Dialog Example 
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I n my response to the question concerning system timers in the September issue, I 
stated, “Windows 3.0 exported both SetSystemTimerf) and KillSystemTimerf), 
but Windows 3.1 does not, presumably to discourage their use." I should have been 
more explicit with that statement. The functions are still exported, but Microsoft 
changed their names to BEAR182 and BEAR11 respectively. Thanks to Matt Pietrek for 
pointing this out. Also, in the last sentence I forgot to mention all the authors of 
Undocumented Windows. My apologies to David Maxey and Matt Pietrek. 

Q In the August Q&A column you answered a question on entering video text 
mode from Windows. You chose to use a TSR to make the real-mode video 
calls (int 0x10) since they cannot be called from protected mode. You could have 
used the DPMI service, “Simulate Real Mode Interrupt,” which is interrupt 0x31, func¬ 
tion 0x0300. This would have saved the overhead of your TSR which occupies space 
in every VM in enhanced mode, and saves the bother of having to install the TSR 
before you start up Windows. 


Craig Eisler 
WATCOM 
craig@watcom.on.ca 

A One of the nice things about doing this column is that I learn a lot Usually I 
learn by answering readers’ questions, but it is refreshing to get different (and 
better!) solutions from your feedback. This is definitely a better solution. 

"Simulate Real Mode Interrupt” is part of the DPMI 0.9 specification, so it is avail¬ 
able in both protected modes of Windows 3.x. The interrupt accepts a pointer to a 
structure that contains the register values for the interrupt being simulated (see 
Listing 1). The interrupt, 0x31, is made with the address of this structure stored in 
ES:DI, the interrupt number being simulated in BL with BH set to 0, and the function 
number 0x0300 stored in AX. CX is used to specify the number of bytes to copy 
from the protected-mode stack to the real-mode stack. But if the wSS and wSP fields 
of the structure are set to 0, then DPMI takes care of copying stack data. 

Paul Bonneau 


Send questions to Paul via Internet 
as paul@rdpub.com-, 
from CompuServe: 
>INTERNET:paul@rdpub.com-, 
or in care of this magazine at: 

1601 W. 23rd St., Suite 200 
Lawrence, KS 66046-2743. 


Paul Bonneau is a Senior Software Design Engineer at Microsoft He developed a 
library used in several Microsoft products and was a developer of Hyp erChem, a 
molecular modeling system marketed by Autodesk. The opinions expressed in Paul's 
column are his alone and do not necessarily reflect those of Microsoft 






















Listing 2 is the textmode.c file revisited. Since the window 
procedure, UndProcf), and the utility SetLpvUCw() have not 
changed, they have been omitted. Also, the interface header 
file to the TSR is no longer needed; in its place I’ve included 
the header file of Listing 1. 

The new code relies on the utility routine Video- 
Interrupt () to make all int 0x10 calls. Only those fields of 
the RMI structure (from Listing 1) that are pertinent to the 
particular real-mode interrupt need be initialized, save for wSS 
and wSP, which are set to 0. So Videolnterruptf) sets ivSS 
and wSP to 0, sets up the registers for the Simulate Real Mode 
Interrupt, and executes the int 0x31. In rewriting TextMode, I 
replaced the multiplex interrupt calls (0x2/) to the TSR from 
EnterTextModef) and ExitTextMode() with calls to Video- 
Interrupt (). 

While l was at it, I replaced all the remaining 0x10 video 
interrupts with calls to Videointerrupt() as well. The real¬ 
mode buffer for the video state is obtained using 
GlobalDOSAlloc() (and released with GlobalDOSFreef) on 
exit from the program). GlobalDOSAlloc() allocates memory 
in the first megabyte of linear memory and returns both a 
protected-mode selector and real-mode segment value to the 
memory. The real-mode segment value is used to supply the 
buffer address for the save and restore video state interrupts. 
For some strange reason, Microsoft did not include prototypes 
for GlobalDOSAlloc() and GlobalDOSFree() in windows.h, 
even though they are exported by the kernel. To use these 
functions, you need to provide the proper prototypes (Pascal 
calling convention, implied by the constant UINAPI from win¬ 
dows . h): 


DWORD WINAPI GlobalDOSAlloc(DWORD); 

UINT WINAPI GlobalDOSFree(UINT); 

Undocumented Windows (Schulman, Maxey, and Pietrek — 
Addison-Wesley, 1992) describes a pair of undocumented 
functions, Death() and Resurrection() , which are used by 
GDI to accomplish text-mode toggling. 

Q Would you kindly demonstrate how to highlight 
selected text in a list box string using different colors? I 
understand this can be done using an owner draw style. I do 
have the standard SDK sample of using different background 
colors for an owner-draw list box but I’m not familiar with the 
requirements for outputting text in different colors. I am using 
the system fixed font to align columns. I would like to show 
data in certain columns in a different color to highlight that 
particular item. 

Bud Selfridge 
725 San Mateo Drive 
Menlo Park, CA 94025 

A One approach to solving your problem is to draw each 
list box entry as a series of colored substrings. Before 
each substring is drawn, call SetTextColor() to specify the 
color for that substring. If you use the handy SetTextAlign() 
function with the TAJJPDATECP flag, you don’t even have to 
keep track of the starting position of each substring, since the 
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Listing 1 dpmi.h 

/I*****************************************************/ 

/* dpmi.h 



*/ 

/* -- Interface to 

DPMI 

services. */ 

/★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★Hr************/ 

typedef struct 
/ 



WORD 

w; 

/* 

16-bit register. */ 

WORD 

wHi; 

/* 

32 bit register's high word. */ 

} REG; 


/* 

32/16 view of CPU register. */ 

typedef struct 
/ 



REG 

regDI; 

/* 

DI register. */ 

REG 

regSI; 

/* 

SI register. */ 

REG 

regBP; 

/* 

BP register. */ 

REG 

regZero 

; /* 

Reserved, must be 0. */ 

REG 

regBX; 

/* 

BX register. */ 

REG 

regDX; 

/* 

DX register. */ 

REG 

regCX; 

/* 

CX register. */ 

REG 

regAX ; 

/* 

AX register. */ 

WORD 

wFlags; 

/* 

Flags register. */ 

WORD 

wES; 

/* 

ES register. */ 

WORD 

wDS; 

/* 

DS register. */ 

WORD 

wFS; 

/* 

FS register. */ 

WORD 

wGS; 

/* 

GS register. */ 

WORD 

wIP; 

/* 

Instruction pointer. */ 

WORD 

wCS; 

/* 

CS register. */ 

WORD 

wSP; 

/* 

SP register. */ 

WORD 

wSS; 

/* 

SS register. */ 

} RMI 


/* 

Real Mode Interrupt struct. */ 

/* End of 

File */ 
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Listing 2 textmode.c 


/* textmode.c */ 
/* — Sample program demonstrates 80x25 mode from */ 
/* within Windows. */ 
^★★★★★★★★★★★★★★★★★★★★★********************************^ 


int cbStateBuffer; 

DWORD lw; 

if ((cbStateBuffer * CbGetStateBufferSizeO) «■ -1) 
goto WinMainExit; 


linclude <windows.h> 

linclude <memory 

.h> 

linclude "dpmi.h' 

a 

/***************************************************** 

/* Prototypes. 


/★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★Hr** 

/* Private. */ 
int 

CbGetStateBufferSize(VOID); 

VOID 

ExitTextMode(HWND); 

VOID 

EnterTextMode(HWND); 

VOID 

HandleKey(WPARAM); 

VOID 

SetCursorXY(char, char); 

VOID 

SetLpvWCw(VOID FAR *, WORD, UINT); 

VOID 

VideoInterrupt(RMI *); 

/* Exports. */ 
LRESULT CALLBACK 

WndProc(HWND, UINT, WPARAM, LPARAM); 

/* Imports. */ 
DWORD WINAPI 

G1obalD0SA11oc(DWORD); 

UINT WINAPI 

GlobalDOSFree(UINT); 


if (l(lw = GlobalDOSAlloc(cbStateBuffer))) 
goto WinMainExit; 

segStateBuffer » HIWORD(lw); 
selStateBuffer = LOWORD(lw); 

if (hinsPrev == NULL) 

( 

WNDCLASS wcs; 

/* First instance is responsible for */ 

/* registering a class. */ 
wcs.style = CS_HREDRAW | CS_VREDRAW; 
wcs.lpfnWndProc « WndProc; 
wcs.cbClsExtra = 0; 
wcs.cbWndExtra * 0; 
wcs.hlnstance » hins; 
wcs.hlcon = NULL; 

wcs.hCursor ■ LoadCursor(NULL, IDC_ARR0W); 
wcs.hbrBackground * (HBRUSH)(C0L0R_WIND0W + 1); 
wcs.lpszMenuName * NULL; 
wcs.lpszClassName « szApp; 


/* Constants. */ 

j*★***★*★★★***★★*★**★★★★**★*★★*****★★*****★★***★★★**★★j 

Idefine szApp "Video" 

Idefine dxText 80 

Idefine dyText 25 

Idefine cbText (dxText * dyText * sizeof(WORD)) 

Idefine cbVideoBlock 64 /* Video block in bytes. */ 


if (!RegisterClass(&wcs)) 
goto WinMainExit; 

} 

/* Initialize the video memory. */ 
if (!(hmemText = 

GlobalA11oc(GMEM_MOVEABLE, cbText))) 
goto WinMainExit; 


/* Globals. */ 

/**********★****************************************** j 

/* Imports. */ 
extern WORD _B000H; 


/* Local. */ 

LPWORD lrgwText, lrgwSav; 

char x, y; 

BOOL flnTextMode; 

BOOL fWantTextMode; 

RECT rectWindow; 

WORD selStateBuffer; /* Buffer selector. */ 

WORD segStateBuffer; /* Real mode segment. */ 

BYTE bModeSav; /* Previous video mode. */ 


/* Routines. */ 


int FAR PASCAL 


WinMain(HINSTANCE hins, HINSTANCE hinsPrev, LPSTR lsz, 
int wShow) 

/a****************************************************/ 


/* — hins 
/* — hinsPrev 
/* -- lsz 
/* — wShow 
/ 


This program's instance. */ 
Previous program's instance. */ 
Command line I was invoked with. */ 
ShowWindow command. */ 


★Ik***************************************************/ 


{ 


MSG msg; 

HGLOBAL hmemText = NULL; 

HWND hwnd; 


lrgwSav ■ (LPWORD)GlobalLock(hmemText); 
lrgwText = 

(LPWORD)MAKELONG(0x0000, (WORD)&_B000H); 
SetLpvWCw(lrgwSav, 0x0720, dxText * dyText); 

/* Create the main window. */ 
hwnd * CreateWindow(szApp, szApp, 
WS_OVERLAPPEDWINDOW, 

CWJJSEDEFAULT, CWJJSEDEFAULT, 
CWJJSEDEFAULT, CW_USEDEFAULT, 

NULL, NULL, hins, NULL); 

if (!hwnd) 

goto WinMainExit; 

ShowWindow(hwnd, wShow); 

while (GetMessage(&msg, NULL, 0, 0)) 

{ 

TranslateMessage(&msg); 
DispatchMessage(&msg); 

) 

WinMainExit: 

if (selStateBuffer) 

GlobalDOSFree(selStateBuffer); 
if (hmemText) 

GlobalFree(hmemText); 
return 0; 

1 


VOID 

SetCursorXY(char x, char y) 
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Listing 2 continued 


j******************************************★★★★★★*★★**j 

/* — Set the cursor position. */ 

/ *****************************************************J 

f 

RMI rmi; 

rmi.regDX.w * x + (y « 8); 
rmi.regBX.w * 0; 
rmi.regAX.w * 0x0200; 

VideoInterrupt(&rmi); 

} 

VOID 

EnterTextMode(HWND hwnd) 

j*****************************************************i 


/* -- Enter 80x25 text mode. */ 
/* — Resize the window to full screen, to prevent */ 
/* any other window from being drawn (will cause */ 
/* true nastiness when VGA is in text mode!). */ 
/* -- hwnd : Main window. */ 


j*****************************************************j 

{ 

RMI rmi; 

if (flnTextMode) 
return; 

ShowCursor(FALSE); 

/* Save video state in buffer. */ 
rmi.regAX.w = OxlcOl; 
rmi.regBX.w * 0x0000; 
rmi.regCX.w * 0x0007; 
rmi.wES » segStateBuffer; 

VideoInterrupt(&rmi); 

/* Remember current video mode. */ 
rmi.regAX.w = OxOfOO; 

VideoInterrupt(&rmi); 
bModeSav « LOBYTE(rmi.regAX.w); 

/* Set 80x25 text mode. */ 
rmi.regAX.w = 0x0007; 

VideoInterrupt(&rmi); 

/* Restore previous text. */ 

_fmemcpy(lrgwText, lrgwSav, cbText); 

/* Restore cursor position. */ 

SetCursorXY(x, y); 

/* Save old window position. */ 

GetWindowRect(hwnd, SrectWindow); 

/* Make full-screen and topmost. */ 

SetWindowPos(hwnd, HWND_T0PM0ST, 0, 0, 
GetSystemMetrics(SMCXSCREEN), 

GetSystemMetrics(SMCYSCREEN), SWP_N0ACTIVATE); 

flnTextMode = TRUE; 

) 

VOID 

ExitTextMode(HWND hwnd) 

J*****************************************************J 

I* -- Re-enter previous VGA mode Windows was in. */ 
/* -- hwnd : Main window. */ 

J*****************************************************j 

{ 

RMI rmi; 


if (IflnTextMode) 
return; 

/* Restore previous video mode. */ 
rmi.regAX.w * bModeSav; 

VideoInterrupt(&rmi); 

/* Restore previous VGA state. */ 
rmi.regAX.w = 0xlc02; 
rmi.regBX.w * 0x0000; 
rmi.regCX.w = 0x0007; 
rmi.wES * segStateBuffer; 

VideoInterrupt(&rmi); 

flnTextMode = FALSE; 

ShowCursor(TRUE); /* Restore cursor. */ 

/* Restore old window position. */ 

SetWindowPos(hwnd, HWND_N0T0PM0ST, 
rectWindow.left, rectWindow.top, 
rectWindow.right - rectWindow.left, 
rectWindow.bottom - rectWindow.top, 
SWP_NOACTIVATE); 

InvalidateRect(NULL, NULL, TRUE); 

} 

VOID 

HandleKey(WPARAM wKey) 

J*****************************************************J 

/* — Handle a key event. */ 

j*****************************************************J 

( 

if (IfWantTextMode || IflnTextMode) 
return; 

switch (wKey) 

( 

default: 

( 

WORD wVideo; 

int iw; 

wVideo = 0x0700 | (wKey & OxOOff); 
iw ■ x + y * dxText; 
lrgwText[iw] = lrgwSav[iw] * wVideo; 
if (++x >= dxText) 

{ 

x = 0; 

if (++y >= dyText) 

y = 0; 

) 

} 

break; 

case VK_UP: 

if (-y < 0) 

y * dyText - 1; 
break; 

case VK_D0WN: 

if (++y >= dyText) 
y = 0; 
break; 

case VK_LEFT: 
if (—x < 0) 

x = dxText - 1; 
break; 
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current position will be updated after a text drawing function 
is called. 

Listing 3 is the header file for a sample routine, Draw- 
List (), to be called on receipt of the WM_DRAMITEM message. 
It contains a type definition for the struct SSD. This struct 
specifies a color and character position for the current substr¬ 
ing. Listing 4 is the C code for DrawListf). DrawListf) accepts 
the LPDRAUITEMSTRUCT that is passed via the IParam of the 
UM_DRAUITEM message. It also accepts an array of SSD' s and 
the size of the array. 

If the flags passed via the itemAction field of the 
DRAUITEMSTRUCT specify that the string is to be completely 
redrawn or that its selection state has changed, the routine 
DrawListItem() is called to erase the background of the 
string in the appropriate color (I chose black for selected, and 
white for unselected), and to output the multicolored string. 
Since the background has now been erased, if the state flag 
field, itemState, specifies that the item has a caret, Draw- 
FocusRect() is called to restore it Otherwise, if only the state 
of the caret for the item has changed, a single call to Draw- 
FocusRectf) will suffice, since each call toggles the caret's 
visibility (the operation of drawing the caret is an XOR). 


DrawListltemf) assumes that the list box is created with 
the LBS_HASSTRINGS style. This puts the onus on the list box 
to maintain the strings, but the string must be explicitly 
retrieved (ListBox_GetText() is a windowsx.h macro that 
sends a LB_GETTEXT message to the list box). Contrary to what 
one might expect, the string is not available in the itemData 
field. ExtTextOut() is used to erase the background, since it 
only uses the background color and does not rely on a brush. 


Listing 3 drawlisth 


y *****************************************************j 

/* drawlist.h */ 

/* — Interface to DrawList function. */ 

y*****************************************************y 

typedef struct 
{ 

int ich; /* Index of starting character. */ 

COLORREF clr; /* Color for this substring. */ 

) SSD; /* Sub-String Definition. */ 

VOID DrawList(LPDRAWITEMSTRUCT, SSD *, int); 

/* End of File *1 


Listing 2 continued 


case VK RIGHT: 

SetCursorXY(x, y); 

if (++x >* dxText) 

) 

x = 0; 


break; 

int 

CbGetStateBufferSize(VOID) 

case VK PRIOR: 

j ***************************************************** j 

y = 0 ; 

1* -- Get the size of the buffer required to hold */ 

break; 

/* the video state data. */ 

/* — Return -1 if adapter does not support save/ */ 

case VK NEXT: 

/* restore video state. */ 

y = dyText - 1; 

! ***************************************************** j 

break; 

{ 

RMI rmi ; 

case VK HOME: 


x * y * 0; 

rmi.regAX.w * OxlcOO; 

break; 

rmi.regCX.w « 0x0007; 

VideoInterrupt(&rmi) ; 

case VK END: 

return (rmi.regAX.w & OxOOff) «« 0x001c ? 

x = dxText - 1; 

rmi.regBX.w * cbVideoBlock : -1; 

y = dyText - 1; 

) 

break; 



VOID 

case VK RETURN: 

Videointerrupt(RMI * prmi) 

O 

1 

II 

X 

! ****************** *************************************j 

if (++y >= dyText) 

/* — Use the DPI Simulate Real Mode Interrupt to make */ 

( 

/* the interrupt call. */ 

RMI rmi ; 

! ******************************************************* j 
( 

prmi->wSS = 0; 
prmi->wSP « 0; 

y • dyText - 1; 

/* Scroll the window. */ 


rmi.regAX.w = 0x0601; 

asm mov ax, 0x0300; 

rmi.regBX.w = 0x0700; 

asm mov bx, 0x0010; 

rmi.regCX.w = 0; 

asm mov cx, 0x0000; 

rmi.regDX.w = 

asm push ds; 

dxText - 1 + ((dyText - 1) « 8); 

asm pop es; 

VideoInterrupt(Srmi) ; 

asm mov di , prmi ; 

} 

asm int 0x31; 

break; 

} 

} /* End switch wKey. */ 

/* End of File */ 
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Once the text alignment is set with SetTextAlignf), the call 
to TextOutf) at the bottom of the loop ignores the x and y 
parameters, and relies solely on the current position. Thus the 
current position must be initialized with MoveTof). 

The body of the loop then determines the length of the 
current substring by subtracting the current starting position 
from the next substring's starting position, or the length of the 
entire string if we are at the last substring in the array. The 
length of the substring is checked against the entire string 
length to prevent drawing off the end of the string. Another 
test is performed to prevent calling TextOutf) if the end of 
the string has already been reached. DrawListltemf) does 
not take special action if the itemState field specifies that the 
string is disabled. Perhaps you could modify the colors used to 


half intensity, or maybe change the background color to a 
medium gray. 

Q ln your column in the September 1992 issue you took 
up the issue of tabs to a listbox. Your magazine is great, 
and your article was good but not totally correct. Neither 
taking the character position and multiplying by four nor using 
the more traditional method supplied in the SDK will work 
correctly in a lot of cases. The average character size will be 
too small and will cause a given string to overrun to the next 
tab stop. Even using TEXTMETRIC to retrieve the tmMaxChar- 
Size will in some cases cause an overrun. The information 
concerning the two methods of retrieving the size from the 
system font is not correct either: what is returned is the size 


Listing 4 drawlist.c 



if (1pdis->itemID ■■ -1 || 

/* drawlist.c */ 

! (hfnt = (HFONT)GetStockObject(ANSI FIXED FONT))) 

/* — DrawListO function. */ 

return; 

y*★★★*★***★****★**★*★★*★★**★★***★★★★**★****★★★★*******y 


szBuf[0] = 1 \0 1 ; 

^include <windows.h> 

if ((cchString ■ ListBox GetText(lpdis->hwndItem, 

#include <windowsx.h> 

1pdis->itemID, szBuf)) «■ LB ERR) 

#include "drawlist.h" 

return; 

VOID DrawListItem ( LPDRAWITEMSTRUCT, SSD *, int); 

/* Erase background. Use black if selected. */ 
if (lpdis->itemState & ODS SELECTED) 

VOID 

SetBkColor(1pdis->hDC, 0x00000000) ; 

DrawList(LPDRAWITEMSTRUCT lpdis, SSD * rgssd, int cssd) 

ExtTextOut(lpdis->hDC, 0, 0, ET0 OPAQUE, 

y*****************************************************y 

&lpdis->rcltem, NULL, 0, NULL); 

/* -- Draw a list box string. */ 


/* -- lpdis : Windows DrawItemStruct pointer. */ 

SetTextAlign ( 1pdis->hDC, TA UPDATECP) ; 

/* -- rgssd : Array of Substring definitions. */ 

MoveTo(lpdis->hDC, 0, lpdis->rcItem.top) ; 

/* -- cssd : Size of array. */ 

SelectObject(lpdis->hDC, hfnt); 

y★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★*★★★★★★★★★★★★★★★★★★★y 


{ 

for (issd = 0; issd < cssd; issd++) 

if (lpdis->itemAction & 

{ 

(ODA DRAWENTIRE | ODA SELECT)) 

/ 

int cchSubString; /* Substring length. */ 

DrawListItem(lpdis, rgssd, cssd); 

SetTextColor(lpdis->hDC, rgssdfissd].clr) ; 

if (lpdis->itemState & ODS FOCUS) 


{ 

/* Determine length of this substring. */ 

/* Redraw erased caret. */ 

if (issd -■ cssd - 1) 

DrawFocusRect(lpdis->hDC, &lpdis->rcltem) ; 

( 

1 

/* Last substring, draw to end. */ 

} 

cchSubString ■ cchString; 

else if (lpdis->itemAction & ODA FOCUS) 

1 

I 

else 

/* Toggle caret. */ 

{ 

DrawFocusRect(lpdis->hDC, 8.1pdis->rcltem) ; 

/* Interior substring, draw to next. */ 

} 

/* Don't draw off end. */ 

} 

if ((cchSubString = rgssd[issd + 1].ich) > 
cchString) 

VOID 

cchSubString « cchString; 

DrawListItem(LPDRAWITEMSTRUCT lpdis, SSD * rgssd, 

} 

int cssd) 


y*****************************************************y 

/* Subtract off base. */ 

/* .. Draw a list box string in different colors. */ 

if ((cchSubString -« rgssd[issd].ich) > 0) 

/* -- lpdis : Windows DrawItemStruct pointer. */ 

Text0ut(lpdis->hDC, 0, 0, 

/* -- rgssd : Array of Substring definitions. */ 

szBuf + rgssd[issd].ich, cchSubString); 

/* -- cssd : Size of array. */ 

) 

/★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★■A-** y 

) 

{ 

/* End of File */ 

int issd; /* Substring index. */ 

int cchString; /* Length of entire string. */ 

HFONT hfnt; /* Font to use. */ 

char szBuf[100] ; /* Text buffer. */ 
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of the font that is being used in the listbox at the time — 
which, in the case of just multiplying by four, can cause your 
tabs to be set way off. Using GetDialogBaseUnitsQ adjusts 
the tab size automatically to the size of the currently selected font 

Dean A. McCoy 
Doubleword 
12976 Madrona Leaf Court 
Grass Valley, CA 95945 

A I agree with you completely that overruns into the next 
tab position can be a problem. However, in his letter Mr. 
Katz stated, “This method guarantees alignment so long as 
each tab stop is set past the longest entry for that column.’’ 
My reply was in this context as well. 

The LBSETTABSTOPS message accepts a parameter ex¬ 
pressed in “dialog units." According to the SDK's on-line help, 
“one horizontal dialog box unit is equal to one-fourth of the 
current dialog box base width unit.” Consequently, expressing 
a tab stop in “dialog units" is equivalent to expressing it in 
quarters of the average width of a character in the current 
font. Therefore you can express a tab stop in terms of the 
average current font character width by multiplying the re¬ 
quired character position for the tab by four. 

When the list box is created, the average width of a char¬ 
acter in the current font is obtained and stored in a private 
block of memory used by the list box. Each time the UM_SET- 
TABSTOPS message is received, this value is used to create a 
local array of logical pixel values for the tab stops. When 
tabbed text is drawn by a list box with the LBS_USETABSTOPS 


system, a series of ExtTextOutf) calls are made, one for each 
tab-delimited string, using the next tab stop in the logical pixel 
position array whenever a tab to be drawn is encountered in 
the text. If a dialog template has a FONT statement that 
specifies a non-system font, the list box will use that font 
when it calculates the average character width. So the 
method of multiplying by four has the advantage that it does 
not tie you to a specific font. If you use GetDialogBase- 
Units() as you suggest, the tab stops would be in terms of 
the system font, regardless of any font statement specified in 
the dialog template. 

If you dynamically change the list box’s font to a larger 
font, (with the UM_SETFONT message), then yes, you will see 
overruns into the next tab position. This could simply be an 
oversight on Microsoft’s part. Each time a list box receives a 
WM_SETFONT message, it does adjust the value of the average 
character width in its private data segment, but does not 
recalculate the pixel values of the tab stops. This problem can 
be overcome if you resend the LB_SETTABSTOPS message after 
a WM_SETFONT-, this forces the pixel values of the tab stops to 
be recalculated. 

As you point out, these steps are still not bulletproof. Since 
the average character width is being used, some strings will 
still cause an overrun, (a string of Ws for example). The only 
way to guarantee that overrun will not occur is to preprocess 
the strings. The length of each tab-delimited string segment 
could be determined with GetTextExtentf) and the maxi¬ 
mum value for each tab position obtained. The array of tab 
positions could then be adjusted accordingly, o 
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Write Your Own 


George Toft 


Many people, indeed, many books, treat DOS and the command interpreter as 
one and the same. Or they completely ignore the command interpreter and refer to 
all computer operations as being related to DOS. This is certainly not true. DOS is just 
an operating system. It performs simple procedures such as keyboard input, display 
output, open/close files, delete/rename files, etc. The command interpreter or¬ 
chestrates these simple operations into useful commands. 

To further clarify their roles, consider the interpreter command to display a direc¬ 
tory: DIR. DOS is not capable of obtaining a directory listing of a disk. What it can do, 
however, is find the name of the first file that matches your specification and find 
the next file that matches the previously defined specification. By calling these func¬ 
tions and observing the returned results, the command interpreter (not DOS) per¬ 
forms the DIR command. 

The command interpreter is responsible for receiving your keyboard input, pars¬ 
ing it, performing the tasks it knows, and passing the others on to the command 
execution routine assuming the command is an executable file. In the case of the 
DIR command, the command interpreter knows how to display a directory, so it 
performs the steps shown in Figure 1 (the numbers in parenthesis represent the DOS 
INT 21h function number that performs the step indicated). 

As you can see, the command interpreter performs all the high-level work, and 
DOS performs the low-level, machine-dependent tasks. You could write a command 
interpreter for any operating system, if you knew how to make calls to the operat¬ 
ing system. In fact, some computers that use a command-line based interpreter 
have the ability to review the last several pages of screen data that have scrolled 
off. You could write a replacement command interpreter for DOS with this feature. 

MS-DOS’ Modular Design 

The operating system {/.vsdos.sys or ibmdos.com) is loaded during startup, after 
the input/output routines ( io.sys or ibmbio.com) are loaded. DOS then processes 
the configuration file (config.sys), and then loads and executes the command inter¬ 
preter ( command. com). 


George Toft is currently stationed on board a fast attack submarine in Hawaii. In his 
spare time, he writes utilities and application programs. He has been writing articles 
for computer magazines since 1988. George can be contacted at 92-902 Welo St, #94, 
Makakilo, HI 96707. 
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command.com 


This modular design allows you to replace the default command interpreter with 
one of your own design, as long as it is named command.com, or its name is specified 
in config.sys with the line: 

SHELL=pathname\filename.ext parameters 

Since you can write any kind of command interpreter you want, this opens the door 
to graphical interfaces, menus, password-enabled startups and logins, virtual screens 
with more than 25 lines, and artificial intelligence, just to name a few. 

You can replace command, com with a program written in any language that can 
produce an .exe or .com file. The command interpreter in this article was written in 
Borland’s Turbo Pascal, and compiled to the file command.exe. To force DOS to load 
this new command interpreter, add the following line to config.sys-. 

SHELL = COMMAND.EXE /P 

This tells DOS to load command.exe from the root directory (you could specify a 
complete path if you want) as the command interpreter. DOS has no idea what the 
IP parameter is, nor does it care. DOS dutifully places the parameters in the Program 
Segment Prefix (PSP) so the command interpreter receives parameters just as if they 
were passed from the command line, command.exe uses the IP parameter for the 
same function as the MS-DOS command.com - to prevent unloading the interpreter if 
the user types “EXIT." 

To demonstrate how easy it is to replace the command interpreter, follow these 
steps to make your BASIC interpreter your command interpreter: 

• Format a floppy disk in drive A: using the IS option to put DOS on the disk. 

• Copy your BASIC interpreter (gwbasic.exe , basica.com, or qbasic.exe) onto the 
floppy disk. 

• Place the text “SHELL = QBASIC.EXE" in the config.sys file on drive A.-. If your 
BASIC interpreter is gwbasic.exe or basica.com, use that name instead of 
qbasic.exe. 

• Reset your computer. 

After resetting your computer, it will boot up and load your BASIC interpreter. 
Note, however, if you exit the BASIC interpreter using the “SYSTEM" command, DOS 
will issue the error “Bad or missing command interpreter” and lock up your com¬ 
puter. This is why you should use a floppy drive for this experiment and not your 
hard drive. 
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Figure 1 Executing the “dir" command 


Print directory header (09h) 

Parse the file specification from the command line 
Call the Find_first function (llh) 

If Find_first returns an error. 

Display "File not found" (09h) 

Otherwise, 

Loop while no error 

Print retrieved file name and the file's size (09h) 
Call Find_next function (12h) 

Display amount of disk free space (36h) 


There are no specific hardware problems to account for 
when developing a new command interpreter. If you are 
developing a graphical interface, you must, of course, consider 
the various video adapters the interpreter will run on. You are 
your own best judge of controlling how much RAM your inter¬ 
preter will use. 

Writing Your Own Command Interpreter 

There are performance considerations you must take into 
consideration when developing a command interpreter. These 
include memory usage, using resident and transient code, and 
the need for batch file processing. You might want to make 
use of extended memory if your target computers have it. 
Resident and transient coding, or overlays, will squeeze out 
every last byte of RAM, yet provide a robust command set. If 


you only want to load a menu program, consider excluding 
commands and batch file capabilities to save RAM. 

The features you include in your own command interpreter 
are limited mostly by your own imagination and resourceful¬ 
ness. By using overlay programming, your command inter¬ 
preter can have numerous bells and whistles that haven’t 
been thought of before. 

Example Command Line Interpreter 

Listing 1 contains the Turbo Pascal source code for an ex¬ 
ample command line interpreter. This interpreter is a just a 
shell with a few functions filled in. It is, however, fully func¬ 
tional, and it operates with DOS version 3.0 through 5.0. DOS 
version 2 doesn’t support the “SHELL =" command in con- 
fig. sys. 

The example interpreter supports the following commands 
and functions: CD, CLS, COPY, DEL, EXIT, REM, and VER. These 
functions serve the same purpose and syntax as their DOS 
equivalents, with the exception of COPY and VER. The COPY 
command requires both the source and destination files or 
devices be specified, and it does not support wildcards. VER 
displays both the DOS and the command interpreter version 
numbers. 

The compiled version of the interpreter uses less than 
11Kb and runs batch files, executes programs, shifts drives, 
changes directories, and performs the previously mentioned 
internal commands. You can easily change the interpreter’s 
capabilities depending on your needs. 


Listing 1 command.exe 

f ***********★*********************************************) 

Security, ( TRUE if password required ) 

(*++ 


Execute, ( TRUE if need to execute a file ) 

(* COMMAND.EXE - Replacement command line interpreter *) 

OK to Exit, { TRUE if OK to exit process loop } 

(* 

*) 

Batch File: ( TRUE if a batch file is running ) 

(* Language: Borland 

Turbo Pascal 5.5 *) 

Boolean; 

(* Author: George R. Toft *) 

Text File, ( general purpose I/O file ) 

(* Date: 23 Dec 

91 *) 

In File: ( Console input file ) 

(* Notes: Copyright 1990, 1991 George Toft. *) 

Text; 

(* 

92-902 Welo St, #94 *) 

Regs: { Registers used in MS-DOS calls } 

(* 

Makakilo, HI 96707 *) 

Registers; 

(*** 

***\ 


/Ik******************************************************** J 

(* This section contains Pascal language enhancements *) 

(*$M 8192, 0, 0 *) ( 

allocate 8K stack, no heap ) 




{ StrUp returns the uppercase version of string S } 

Uses 


Function StrUp(S: String): String; 

DOS, 1 

DOS for access to MSD0S functions ) 

Var 

CRT; 1 

For ClrScr function ) 

Count: Integer; 

Const 


begin 

Unknown Command = 

'Bad command or file name.'; 

for Count :« 1 to Ord(S[0]) do 

Max Token 

20; { 20 tokens per line } 

S[Count] := UpCase(S[Count]) ; 

Type 


StrUp := S 

Token Type = 1 

Type def'n for param declarations ) 

end; ( StrUp } 


array[l..Max Token] of String; 


Var 


function File Exists(Filename: String): Boolean; 

Input Command: I 

Var to hold input command ) 

{ To include a search path when executing a program. 


String; 

add it in the File Exists function, make the 

Token: 1 

tokens parsed from Command } 

function parameters pass by reference so that 


Token Type; 

Command Head includes the path to the file. } 

Token Count: 1 

Number of tokens } 

begin 


integer; 

Assign(Text File, Filename); 

Current Dir: 1 

Current directory on disk } 

(*$I-*) Reset(Text File); (*$I+*) 


String; 

if (IOResult * 0) then 

Current Drive: 1 

Current disk, 0=A. 1=B, 2-C ... } 

begi n 


Integer; 

close(Text File) ; 

Count: i 

Counter) 

File Exists := TRUE 


Integer; 

end 

Permanent_COMMAND, { Status of transient C0MAMND.EXE } 
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Program Description 

The interpreter begins by displaying an introductory mes¬ 
sage, then calls Initialize, which determines the current 
drive and directory name. Next, the interpreter examines the 
command line parameters. A IP, for permanent interpreter, 
sets the variable Permanent_COMMAND to TRUE and prevents 
unloading the interpreter after receiving the EXIT command. A 
/C sets the variable Execute to TRUE, and tells the interpreter 
to process a command, and when finished, receive input from 


the keyboard. A /S sets the variable Security to TRUE and 
forces the user to enter the password contained in the file 
password, sec before startup continues. The password is not 
encoded nor is it very secure. It is included to show how a 
simple password entry system works. If you use a password 
system, use an encryption/decryption scheme to prevent its 
disclosure, and create a change password program. 

After the password is entered (if applicable), the interpreter 
attaches its input to the console, or STDIO. If a batch file is to 
be processed, the input will be directed to that file, which will 


Listing 1 continued 


else 

Wildcards are not supported. To add wildcards. 

File Exists :« FALSE; 

use the FindFirst and FindNext DOS unit procedures 

end; { File_Exists ) 

in a loop to process all the wildcards. } 
begin 

(* This sect, conteins Compiler/Interpreter necessities *) 

Assign(Text File, Token[2]); 

(*$I-*) Reset(Text File); (*$I+») 

Procedure Perse(In Line: String; 

if (IOResult * 0) then 

VAR Token: Token Type; 

erase(Text File) 

VAR Token Count: Integer); 

else 

var 

writelnf'File ', Token[2], ' not found.') 

Count: { Scans bytes in In Line ) 

end; ( Del File ) 

byte; 


begin 

Procedure Copy File(File S, File D: String); 

Token Count :* 0; 

( This procedure copies the source file. File S, to 

Count := 1; 

the destination file. File D. Wildcards are not 

FillChar(Token, SizeOf(Token), 0); 

supported. To add wildcards, use the FindFirst and 

repeat 

FindNext DOS unit procedures in a loop to process 

while (In Line[Count] = ' ') AND 

all the wildcards. This code is based on an example 

(Count <• length(In Line)) do 

provided by Borland in their help facility. ) 

inc(Count); 

var 

if (Count <- 1ength(In Line)) then 

Bin File S, ( Source binary file } 

begin 

Bin File D: ( Destination binary file ) 

inc(Token Count); 

file; 

While (In Line[Count] <> ' ’) 

Copy Buffer: ( Intermediate storage location ) 

and (Count «* lengthen Line)) do 

array [1..4096] of byte; 

begin 

Num Read, { Number of bytes read ) 

Token[Token Count] := Token[Token Count] 

Num Written: { Number of bytes written ) 

+ In Line[Count]; 

integer; 

inc(Count) 

begin 

end 

if (File S * File D) then 

end 

writeln('File cannot be copied onto itself.') 

until (Count > length(In Line)) 

else 

end; ( Parse ) 

begin 

Assign(Bin File S, File S); 

Procedure Split Cornnand(Comnand: String; 

(*$I-») Reset(Bin FileS, 1); (*$I-*) 

VAR Command Head, 

if (IOResult <> 0) then 

Command Tail: String); 

writeln('File ', File S, ' does not exist.') 

begin 

else 

if (Pos(' Command) = 0) then 

begin 

begin 

Assign(Bin File D, File D); 

Command Head :- Command; 

Rewrite(Bin File D, 1) ; 

COmmand Tail :» ' ' 

writeln('Copying ', FileSize(Bin File S), 

end 

' bytes . . . ' ); 

else 

repeat 

begin 

BlockRead(Bin File S, Copy Buffer, 

Command Head := Copy(Command, 1, Pos( 1 Command)-l); 

4096, Num Read); 

Command Tail := Command; 

BlockWrite(Bin File D, Copy Buffer, 

Delete(Command Tail, 1, Length(Command Head)) 

Num Read, Num Written); 

end 

until (Num read = 0) OR (Num read <> Num Written); 

end; { Split Command } 

close(Bin File S) ; 


dose(Bin File D) 

(* This section contains DOS functions *) 

end 

end 

Procedure Display Version; 

end; { Copy File } 

begin 

Regs.AH :■ $30; 


Regs.AL := $00; 

Procedure Execute Command(Command: String); 

MSDos(Regs) ; 

var 

writeln(#10, 'MS-DOS version Regs.AL, Regs.AH); 

Command Head, { Command to be executed } 

writeln (' Command interpreter version 1.0') 

Command Tail: ( Parameters for Command Head ) 

end; ( Display_Version ) 

String; 

Procedure Run Program; 

Procedure Del File(File To Delete: String); 

begin 

( This procedure deletes the file, File_To_Delete, 

SwapVectors; 


December 1992 


Windows/DOS Developer's Journal — Page 55 







Listing 1 continued 


exec(Command Head, Command Tail); 

writeln (' Drive is not accessible.') 

SwapVectors; 

end; { Shift_Drive } 

if (DosError <> 0) then 


writeln(Unknown Command); 

Procedure Change Dir(New Dir: String); 

end; { Run Program ) 

begin 

begin 

New Dir :- New Dir + #00; 

Split Command(Command, Command Head, Command Tail); 

Regs.AH :> $3B; 

{ check for extension. If missing, check for .BAT, 

Regs.DS :* Seg(New Dir[l]); 

.EXE, and .COM files ) 

Regs.DX := Ofs(New Dir[l]); 

if (Pos( 1 . 1 . Command Head) = 0) then 

MSDos(Regs); 

begin 

if ((Regs.Flags AND FCarry) <> 0) then 

if File Exists(Command Head+'.BAT') then 

writeln('Invalid directory.') 

begin 

end; ( Change Dir ) 

Command Head :■ Command Head + '.BAT'; 


Close(In File); 

(* This section contains C0MMAND.EXE routines *) 

if File Exists(Command Head) then 


begin 

Procedure Initialize; 

Batch File :■= TRUE; 

begin 

Assign(In File, Command Head); 

Get Current Drive; 

Reset(In File) 

Get Current Dir 

end 

end; T Initialize } 

else 


writeln(Unknown Command) 

Procedure Get Command Line Parms; 

end 

begin 

else if File Exists(Command Head+'.EXE') then 

Permanent COMMAND :- FALSE; 

begin 

Security :- FALSE; 

Command Head :* Command Head + '.EXE'; 

Execute : = FALSE; 

Run Program 

for Count := 1 to ParamCount do 

end 

begin 

else if File Exists(Command Head*'.COM') then 

( Cannot unload this copy of C0MMAND.EXE ) 

begin 

Permanent COMMAND :* Permanent COMMAND OR 

Command Head ;* Command Head + '.COM'; 

(StrUp(ParamStr(Count)) * '/ P’); 

Run Program 

{ Security enabled - get password later } 

end 

Security := Security OR 

else 

(StrUp(ParamStr(Count)J » '/S'); 

writeln(Unknown Command) 

( Command to execute ) 

end 

if (StrUp(ParamStr(Count)J = ' /C ') then 

else 

begin 

Run Program; 

Execute := TRUE; 

end; ( Execute_Command ) 

Input_Command :» ParamStr(Count+l) 
end 

Procedure Get Current Drive; 

end 

begin 

end; { Get Comamnd Line Parms ) 

Regs.AH :■= $19; 

MSDos(Regs); 


Current Drive :* Regs.AL 

Procedure Get Password; 

end; ( Get Current Drive ) 

var 


Password, ( Password read from disk ) 

Procedure Get Current Dir; 

Input Password: ( Password entered by user ) 

var 

String; 

Count; Integer; 

begin 

begin 

(*$I-*) 

{ Get current directory on current drive } 

Assign(Text File, 'COMMAND.SEC' ); 

for Count := 1 to 255 do 

Reset(Text File); 

Current Dir[Count] := ' '; 

(*$I+*) 

Current DirXo] :* #67; 

if (IOResult = 0) then 

Regs.AH :* $47; 

begin 

Regs.DL :* Current Drive + 1; 

readln(Text File, Password); 

Regs.DS : = Seg(Current Dir[1] ); 

close(Text File); 

Regs.SI :* Ofs(Current Dir[1] ); 

( Insert decrypting code here ) 

MSDos(Regs) ; 

repeat 

{ remove trailing null } 

write('Password: '); 

Count := Ord(Current Dir [0] ); 

readln(Input Password) 

Repeat 

until (Input Password * Password) 

Dec(Count) 

end 

Until (Current Dir[Count] * #0); 

else 

Current Dir[0] ;* Chr(Count-l) 

writeln('No password file exists (COMMAND.SEC).'); 

end; ( Get_Current_Dir } 

end; ( Get_Password ) 

Procedure Shift Drive(New Drive Letter: Char); 


var 

Procedure Process(Command: String); 

New Drive: { Integer value of new drive ) 

{ Internal commands supported: 

Integer; 

CLS - Clears screen 

begin 

VER - Displays version of DOS and interpreter 

New Drive := Ord(New Drive Letter)-65; 

EXIT - Exits the program 

Regs.AH :* $0E; 

DEL - Deletes a file 

Regs.DL New Drive; 

COPY - Copies one file to another 

MSDos(Regs); 

REM - Remark statement 

Get Current Drive; 

CD - Change directory 

if lNew_Drive <> Current_Drive) then 

If anything else is entered, it is assumed to be an 
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drive the interpreter. The only difference between a batch file 
and console input is where the interpreter's commands come 
from. 

If Execute is TRUE, the program loads and executes the 
command specified in the parameter — either a batch file or 
an executable file. An important difference between this inter¬ 
preter and the one provided by Microsoft is that this one 
returns to the keyboard when the specified command is 
finished, and Microsoft's can hang up. If a batch file is being 
processed, the last line must be EXIT, or the command inter¬ 
preter will shift over to the keyboard for input If Execute is 
FALSE, the interpreter looks for autoexec.bat. If autoexec.bat 
exists, the interpreter opens it up to receive input commands. 

The Repeat ... Until loop is the heart of the interpreter. 
It loops until the EXIT command is issued, or the end of the 
current batch file is reached and the interpreter is not in the 
permanent residence mode (Permanent_COMMAND = TRUE). In¬ 
side the loop, the interpreter prints the prompt, hard-coded to 
be the drive and directory information, then gets a line from 


the input device (keyboard or batch file). If a batch file is run¬ 
ning, the variable Batch_File is TRUE, and the input line is 
echoed back to the display. If you implement the ECHO OFF 
command, change this If ... Then to display the prompt 
only if the echo status is ON. 

Next, the interpreter checks to see if the EXIT command 
was issued with the interpreter in the permanent residence 
mode. If so, the input command is blanked. Otherwise, the 
input line is processed by the Process procedure. The 
remainder of the loop implements the loop termination se¬ 
quence. 

Process performs the actual decoding of the input line. It 
parses the input line into tokens and stores each token in the 
Token [] array. Token_Count indicates how many tokens there 
are. Then, Process compares Token [1] with its list of built-in 
command names. 

The procedure Execute_Comnand is worth discussing as its 
program search criteria are exactly opposite those of 
Microsoft’s. Instead of looking for .com, then .exe, then .bat 


Listing 1 continued 


external command. The file search begins with .BAT, 

Batch File FALSE; 

.EXE, then .COM files (reverse of COMMANO.COM). ) 

if Execute then 

begin 

Process(Input Command) 

P«rse(Comnand. Token, Token Count); 

else 

{ Note: You can increase the execution speed by 

begin 

placing the Parse() command only where needed. 

{ if AUTOEXEC.BAT exists, get input from the 

This will, however, increase the size of the 

batch file and run it j 

.EXE file. ) 

Batch File File Existsf'AUTOEXEC.BAT'); 

if (Token[l] - " CLS ‘ ) then 

if Batch File then 

ClrScr 

begin 

else if (Tokenfl] » ' VER*) then 

Close(In File); 

Display Version 

Assign(In File, 'AUTOEXEC.BAT'); 

else if (Tokenfl] * ’DEL’) then 

Reset(In File); 

Del File(Token[2]) 

end 

else if (Tokenfl] - 'COPY') then 

end; 

if (Token Count <> 3) then 

( Loop until 'Exit' comnand issued or end of batch file ) 

writeTn('Usage: COPY d:\path\filename.ext ', 

OK to Exit :■= FALSE; 

'd:\path\filename.ext') 

Repeat 

else 

{ Display prompt ) 

Copy File(Token[2], Token[3]) 

Get Current Drive; 

else if (Tokenfl] - 'REM') OR (Tokenfl] * ") then 

Get Current Dir; 

( do nothing } 

write(chr(65+Current Drive), ' : \' , Current Dir, ’>'); 

else if ( (Token[1][2] = ':') AND 

( Get cormand ) 

(Length(Token[l]) * 2)) then 

readln(In File, Input Command); 

Shift Drive(Tokenfl][1]) 

( change this IF..THEN when ECHO OFF is implemented } 

else if (Tokenfl] * 'CD') then 

if Batch File then 

Change Dir(Token[2]) 

writeln(Input Command); 

else { execute command ) 

{ Shift input commanbd to uppercase for processing } 

Execute Command(Comnand); 

Input Command :* StrUp(Input Command); 

end; ( Process ) 

( If 'exit' command issued after '/P ' permanent 

begin ( Program ) 

parameter, then ignore command; otherwise, 
perform command ) 

if (Input Command * 'EXIT') AND Permanent COMMAND then 

( Introduce program ) 

Input Command " 

writelnCCOMMAND.EXE - replacement command line ', 

else if (Input Command <> 'EXIT') then 

'interpreter for MS-DOS.'#10#13, 

( Process command } 

'This interpreter is for demonstration ', 

Process(Input Command); 

'only and is limited in scope.'#13#10, 

if NOT Batch File then 

'Copryright 1991, 1991 George Toft, ', 

OK to Exit := Input Command * 'EXIT' 

'Makakilo, Hawaii ' #13#10#10) ; 

else 

{ Initialize - get current disk & directory ) 

if E0F(In File) then 

Initialize; 

begin 

( Get command line parameters ) 

OK to Exit := NOT Permanent COMMAND; 

Get Command Line Parms; 

Assign(In File, "); 

( If password enabled, get password } 

Reset(In File) ; 

if Security then 

Batch File := FALSE 

Get Password; 

end 

( Attach input to STDIO ) 

Until OK to Exit 

Assign(In File, "); 

end. 

Reset(In_File); 

( Assume no batch file to run yet } 

{ End of File ) 
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files when you enter a command, it searches for matching 
.bat files, then .exe files, then .cow files. This demonstrates 
that you can change the execution order to whatever you 
want. You could even change the extensions so that. txt files 
are executed instead of .bat files. 

Where to Go from Here 

The first thing you may want to do with this interpreter is 
expand its capabilities. To minimize the size of the interpreter, 
externalize the infrequently used commands, such as TIME, 
DATE, and VER. Write short programs in your favorite language 
to perform these functions. It will cost you more in disk 
storage, but it will save your precious RAM. 


These batch file processing commands should remain inter¬ 
nal to the interpreter: CALL, ECHO, FOR, GOTO, IF, REM, SET, and 
SHIFT. All other commands that Microsoft put in their inter¬ 
preter can easily be externalized without seriously reducing 
batch file execution speed. 

The environment is a series of strings terminated with a 
NULL, just like a string in C, and the last environment string is 
terminated with two NULLs. This interpreter does not manage 
or access the environment space. If your application uses the 
environment for storing any variables, you will want to add 
environment management routines. Scott Ladd shows how to 
find the beginning of the environment space using a few lines 
of assembly code (Ward 1990). 

This example uses all of the default 
error checks built into the Turbo Pascal 
system. To further reduce the size of 
the .exe file, force the compiler to 
remove all range, stack, I/O, and var 
string checking with the (*$R- ,S-,I-,V-*) 
compiler directive, and remove all of 
the (*$l+*) compiler directives. This 
saves about 500 bytes in the final .exe 
file. If you are using any of the Borland 
languages, recompile the source code 
using the command line compiler in¬ 
stead of the developing environment to 
save even more RAM. The development 
environment compiler inserts a lot of 
debugging code, which greatly increases 
the size of the . exe file. 

The choice of language for your in¬ 
terpreter is your own. I chose Pascal 
primarily because it is easy to read and 
preliminary experiments showed the 
Borland Pascal executable code was 
more compact than an equivalent Bor¬ 
land C program's executable. The most 
important thing to remember when you 
are writing your command line inter¬ 
preter is that it is just another program 
running under DOS. 
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-lint 


5.0 presents 
C Bug #616 



There's something wrong with this function, other than the fact that we're 
missing a few reindeer. Can you or your compiler spot it? Call if you need 
a hint. Refer to Bug # 6 / 6 . 


PC-lint will catch this and inanv other 
C bugs. Unlike your compiler, PC-lint 
looks across all modules of your 
application for bugs and inconsistencies. 

New - Optional Strong Type Checking 
and variables possibly not initialized. 

More than 330 error messages. More 
than 105 options for complete 
customization. Suppress error messages, 
locally or globally, by symbol name, by 
message number, by filename, etc. 
Check for portability problems. Alter 
size of scalars. Adjust format of error 
messages. Automatically generate ANSI 
prototypes for your K&R functions. 


Attn: Power users with huge programs. 

PC-lint 386 uses DOS Extender 
Technology to access the full storage 
and flat model speed of your 386. Now 
fully compatible with Windows 3.0 
and DOS 5.0 

PC-lint 386 -$239 
PC-lint DOS -OS/2- $139 

Mainframe & Mini Programmers 

FlexeLint in obfuscated source 
form, is available for Unix, OS-9, 
VAX/VMS, QNX, IBM VM/MVS, etc. 
Requires only K&R C to compile but 
supports ANSI. Call for pricing. 




PA add 6% sales lax. 


3207 Hogarth Lane. Collegeville, PA 19426 

CALL TODAY (215)584-4261 Or FAX (215)584-4266 

30 Day Money-back Guarantee. 

PC-lint and FlexeLint are trademarks of Gimpel Software 
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A Drag-and-Drop Shell 

Noah Davids 


Even before the release of Windows 3.1,1 had heard a lot about drag-and- 
drop. Since Windows has always let me launch an application just by double¬ 
clicking on one of its data files —which is faster than dragging a file selection 
to an icon or a window -1 asked myself "What’s the big deal?” I finally 
realized that drag-and-drop comes in handy when I want to run the data file 
with a different application. For example, I have configured Windows to 
launch my program editor when I double-click on a C file. However, to run 
my C programs through my program style checker (also known as lint), I 
have to either change the association for the C file type from the editor to 
lint and then back again or launch the lint application and use its FileOpen 
dialog to open the file. Either way is slower than just dragging the C file 
selection to the lint application’s window. For those applications that do not 
have a clear association with a file type (e.g., my spelling/grammar checker 
and my e-mail applications, both of which accept many types of files), drag- 
and-drop is clearly the method of choice. 

Unfortunately, most of my applications do not support drag-and-drop, 
either because the software developer doesn’t yet provide it or because I 
don't have the latest version. Either way I have a problem — that is, I had a 
problem until I wrote Ddshell. Ddshell is an application that you can configure 
to launch any Windows application or DOS program when a file or group of 
files is dropped on its icon. The only requirement is that the application to be 
launched must take its data file path as a command-line argument 

The first part of this article describes how to use Ddshell. The second part 
describes the Ddshell code, with details of the Windows APIs for both drag- 
and-drop (see Table 1) and private . ini (see Table 2) files. 


Noah Davids works as a technical support specialist at a mid-sized computer 
company, where he specializes in communication problems. He may be 
reached via the Internet at noah@az.stratus.com. 
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Figure 1 Example ddshell.ini file 

Ddshell Usage 

Ddshell.exe can launch any other Windows application or 

[notepad] 

commands:\windows\notepad.exe 

title=NotePad 

xPos=521 

yPos=420 

DOS program. You configure Ddshell with entries in the 
Ddshell.ini file, which is located in your Windows directory. 
Each section of the .ini file contains four entries. The first 
entry is the full path of the command you want executed. The 
path of the dropped file is concatenated with the command 

[browser] 

commands :\winuti1s\browser.exe 

title=Browser 

xPos=447 

yPos=419 

path to create a command line which is then executed. If mul¬ 
tiple files are dropped, then each is concatenated with the 
command path and the resulting command line is executed in 
turn. The second entry is the title that will be displayed on 
the Ddshell icon while it is running (Ddshell runs only as an 

[graphics] 

conmand=c:\graphics\utils\wingif.exe 

title=WinGif 

xPos=378 

yPos=419 

icon). The next two entries are the last x and y positions of 
the icon. These values are updated each time the icon is 
moved. 

Table 1 Drag-and-Drop API 


Name and Function 

Parameters 

void DragAcceptFiles (hWindow, bFlag) 

hWindow is a handle to a window. 

bFlag is a flag —a value of TRUE means that the window will accept dropped files, 

Called to identify to Windows a 
window which will start accepting or 
stop accepting dropped files. 

a value of FALSE means that the window will no longer accept dropped files. 

UJNT DragQueryFile (hDrop, ilndex, 

IpszPath, iMaxPathSize) 

hDrop is a handle to the HDROP structure. 

ilndex is the index of the file dropped. An index of -1 will cause DragQueryFile to 
return the number of files dropped. The first file will have an index of 0. 

Called to obtain the number of files 
dropped and also actual file paths and 
lengths of those paths. 

IpszPath is a pointer to a buffer that will hold a null-terminated string 
representing the path of the ilndex file. The number of characters actually copied 
into the buffer, not including the null-terminated character (if any), will be 
returned by the function. If IpszPath is NULL then DragQueryDrop will return the 
length of the string representing the path. This length will not include the 
terminating NULL character. 

iMaxPathSize is the size of the buffer pointed to by IpszPath. If the actual path is 
longer than iMaxPathSize then only iMaxPath characters are copied to the buffer. 

In this case there will be no null-terminated character. 

BOOL DragQueryPoint (hDrop, IpPoint) 

hDrop is a handle to the HDROP structure. 

IpPoint is a pointer to a POINT structure. 

Called to obtain the coordinates of 
where on the window the files were 
dropped. The function will return 

TRUE if the files where dropped in the 
client area of the window. 


void DragFinish (hDrop) 

hDrop is a handle to the HDROP structure. 

Called when processing of the 
WM_DROPFILES message has been 
completed. It frees memory that 

Windows allocated during the 
DragQueryFile calls. 
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Table 2 Private INI API 


Name and Function 

Parameters 

int GetPrivateProfileString 
(IpszSectiortName, IpszEntryName, 
IpszDefauItValue, IpszBuffer, 
nBufferSize, IpszINIFile) 

IpszSectionName is a pointer to a buffer holding a null-terminated string 
containing the name of the section in the INI file. Comparisons between the value 
in this buffer and the values in the INI file are made independent of case. 
IpszEntryName is a pointer to a buffer holding a null-terminated string containing 
the name of the entry in the section. If this value is NULL then all the entries in 

Called to read a character string 
defined by the specified entry in the 
specified section of the specified INI 
file. The function returns the number 
of bytes copied in the buffer pointed 
to by IpszBuffer. 

the section are copied to IpszBuffer. Each entry is terminated with a NULL 
character and there is a final NULL character following the terminating NULL of the 
last entry. Comparisons between the value in this buffer and the values in the INI 
file are made independent of case. 

IpszDefauItValue is a pointer to a buffer holding a default value used if the entry 
is not defined or the section is not defined or the INI File cannot be found. This 
value must never be NULL and the string must be terminated with a NULL 
character. 

IpszBuffer is a pointer to a buffer where the string defined by the entry will be 
placed. If the entry in the INI file is enclosed in single or double quotes then these 
quotes are removed by Windows before it copies the value into IpszBuffer. 
nBufferSize is an integer that specifies the size of the buffer pointed to by 
IpszBuffer. If the requested data is longer than nBufferSize characters it is 
truncated. 

IpszINIFile is a pointer to a buffer holding a NULL terminating string containing 
the name or path of the INI file. If the string contains just the name then 

Windows assumes that the INI file is in the Windows dir. 

int GetPrivateProfilelnt 
(IpszSectionName, IpszEntryName, 
IpszDefauItValue, IpszINIFile) 

IpszSectionName: see GetPrivateProfileString. 

IpszEntryName: see GetPrivateProfileString. 

IpszDefauItValue: is a default value used if the entry is not defined or the section 
is not defined or the INI file cannot be found. This value must be between 0 and 

Called to read an integer defined by 
the specified entry in the specified 
section of the specified INI file. If the 
specified entry is not found then the 
default value is returned. If the 
specified entry is found and the value 
is an integer then it is returned. If the 
value is not an integer then a 0 is 
returned. If the specified value is an 
alphanumeric string that begins with 
digits then the leading digits are 
treated as a number and returned. 

32,767. 

IpszINIFile: see GetPrivateProfileString. 

BOOL WritePrivateProfileString 
(IpszSectionName, IpszEntryName, 
IpszBuffer, IpszINIFile) 

IpszSectionName is a pointer to a buffer holding a null-terminated string 
containing the name of the section. If the section does not already exist it is 
created. Comparison of the string to section names in the INI file is made 
independent of case. 

Called to create or update the 
specified entry value in the specified 
section of the specified INI file. 

Returns true if the value was written 
else it returns false. Note that if the 
section, entry, and buffer parameters 
are all NULL then Windows will flush 
its INI cache to disk. 

IpszEntryName is a pointer to a buffer holding a null-terminated string containing 
the name of the entry in the section. If the entry does not exist it is created. 
Comparison of the string to the entry names in the section is made independent 
of case. 

IpszBuffer is a pointer to a buffer holding a null-terminated string that contains 
the value of the entry to be written. If the value is NULL then the entry is deleted 
from the section. 

IpszINIFile is a pointer to a buffer holding a null-terminated string containing the 
name or path of the INI file. If the string contains just the name then Windows 
assumes that the INI file is in the Windows dir. If the INI file specified does not 
exist it is created. 
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Listing 1 ddshell.c 


/* DDSHELL.C 

Drop and Drag Shell for Windows applications that do not implement the 
drop and drag paradigm. 

History: 

NSDavids 92-07-01 
Code started 


*/ 

#define STRICT /* define STRICT to provide maximum type safety 

as defined by Microsoft */ 


linclude <windows.h> 
linclude <string.h> 
linclude <dir.h> 
linclude <shellapi.h> 

Idefine WS_WINDOWSTYLE (WS_OVERLAPPED | WS_CAPTION | WS_SYSMENU | WS THICKFRAME) 
Idefine IDM_AB0UT 1 

char szAppName [] = "Drop_and_Drag"; 

LPSTR lpDDInstance; 

char szComnand [MAXPATH + 2]; 

char szTitle [80]; 

int initialXPos; 

int initialYPos; 

long CALLBACK _export WndProc(HWND, UINT, UINT, LONG); 

Ipragma argsused 

I*★*★★**★*★★★★*★★**★*★★*★**★★**★★★★★*★★★★*★★**★★**★************i 

int PASCAL WinMain (HINSTANCE hlnstance, HINSTANCE hPrevInstance, 

LPSTR lpCmdLine, int nCmdShow) 

f 

MSG msg; 

WNDCLASS wc; 

HWND hWnd; 

HMENU hMenu; 

lpDDInstance « lpCmdLine; 

if (IhPrevInstance) 

{ 

wc.style 
wc.lpfnWndProc 
wc.cbClsExtra 
wc.cbWndExtra 
wc.hlnstance 
wc.hlcon 
wc.hCursor 
wc.hbrBackground 
wc.lpszMenuName 
wc.lpszClassName 

RegisterClass(&wc); 

} 

hWnd = CreateWindow(szAppName, NULL, WS_WINDOWSTYLE, CW_USEDEFAULT, 
CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT, 

NULL, NULL, hlnstance, NULL); 


* CS_HREDRAW | CS_VREDRAW ; 

= WndProc; 

* 0 ; 

= 0 ; 

■ hlnstance; 

= Loadlcon (hlnstance, szAppName); 
* LoadCursor (NULL, IDC_ARR0W); 

= GetStockObject (WHITE_BRUSH); 

= NULL; 

= szAppName; 


if (!hWnd) 

return (FALSE); 

hMenu « GetSystemMenu (hWnd, FALSE); 

AppendMenu (hMenu, MF SEPARATOR, 0, NULL); 

AppendMenu (hMenu, MFJTRING, IDM_AB0UT, "About..."); 


Of the four, only the command path 
entry is required; if it is not found, then 
an error will be reported and execution 
will be terminated. If the title entry is 
not found, the section name is used for 
the title. If the x and y positions are not 
found, then Ddshell will let Windows 
position the icon in the next available 
icon slot at the bottom of the screen. 
Figure 1 shows an example 
Ddshell.ini file. 

When the Ddshell application is 
launched, you must provide a section 
name as an argument. If you do not, 
then an error is reported and execution 
is terminated. Several instances of 
Ddshell — each started with a different 
section name — may be run at the 
same time. The section name argument 
can be set with the Program Item 
Properties dialog. Just select the Ddshell 
icon from the program group and then 
select the Properties item from the File 
menu to display the Program Item 
Properties dialog. The section name ar¬ 
gument is appended to the end of the 
command line in the Command Line 
item. The Description item is the title of 
the icon in the program group. I recom¬ 
mend that you use the same title here 
as you set in the Ddshell.ini file, so 
that the program group title matches 
the title on the icon during execution. 
Once an instance of Ddshell is running, 
all you need to do is select a file from 
the FileManager, drag it to the Ddshell 
icon, and drop it 

ddshell.c 

I wrote Ddshell using Borland's Turbo 
C++ version 3.1. However, to allow 
Ddshell to be used as an example, I did 
not use any C++ constructs, just straight 
C code which can be used with any C 
language that supports the Windows 
3.1 API. 

ddshell.c (Listing 1) is a small Win¬ 
dows program consisting of just two 
procedures, UinMain and UndProc. Uin- 
Main sets up the execution environ¬ 
ment while UndProc processes the mes¬ 
sages sent by Windows. To keep the 
code simple, I avoided dialog windows; 
instead, I use the Windows built-in 
MessageBox to report errors. Also in¬ 
cluded here (Listing 2) is the . rc file for 
the Ddshell icon. 

Most of the UinMain procedure is 
straightforward — the calls it uses to 
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Listing 1 continued 


ShowWindow(hWnd, SW_SHOWMINIMIZED); 
if ((initialXPos 1= 0) || (initialYPos != 0)) 

MoveWindow (hWnd, initialXPos, initialYPos, 0, 0, TRUE); 

SetWindowText (hWnd, (LPSTR) szTitle); 

while (GetMessage(&msg, NULL, NULL, NULL)) 

{ 

TranslateMessage(&msg); 

DispatchMessage(Smsg); 

} 

return (msg.wParam); 

) /* end of WinMain */ 


long CALLBACK _export WndProc 

(HWND hWnd, UINT message, UINT wParam, LONG IParam) 

{ 

int xPos; 

int yPos; 

HDROP hDrop; 

int TotalNumberOfFiles; 

char szFileName [MAXPATH + 1]; 

char szString [256]; 

i nt i; 

WORD winExecErr; 

i nt 1en; 

switch (message) 

{ 

case WM_CREATE: 

if (lstrlen (lpDDInstance) == 0) 

( 

wsprintf (szString, "%s %s", 

(LPSTR) "DDSHELL must be called with an", 

(LPSTR) “argument to identify its instance"); 

MessageBox (hWnd, szString, szAppName, 

MB_ICONEXCLAMATION | MB_0K); 

DestroyWindow (hWnd); 
return 0; 

) 

len » GetPrivateProfileString (lpDDInstance, “command", 

"", szCommand, MAXPATH + 2, “ddshell.ini”); 

if (len ** 0) 

f 

wsprintf (szString, 

"No coimand line defined for %s in DDSHELL.INI%s%s", 
lpDDInstance, (LPSTR) "\n or\n", 

(LPSTR) "DDSHELL.INI not found in your WINDOWS DIR"); 
MessageBox(hWnd, 

szString, szAppName, MB_ICONEXCLAMATION | MB_0K); 
DestroyWindow (hWnd); 
return 0; 

} 

if (len > MAXPATH) 

( 

wsprintf (szString, 

"The command line for %s \n%s %i character limit", 
lpDDInstance, (LPSTR) “is longer than the", 

MAXPATH); 

MessageBox(hWnd, 

szString, szAppName, MBJCONEXCLAMATION | MB_OK); 
DestroyWindow (hWnd); 
return 0; 

) 

GetPrivateProfileString (lpDDInstance, "title", 

lpDDInstance, szTitle, 80, "ddshell.ini"); 
initialXPos = GetPrivateProfilelnt 

(lpDDInstance, "xPos", 0, "ddshell.ini"); 


register the Ddshell class, create and 
show the Ddshell window, and imple¬ 
ment the message loop appear in one 
form or another in all Windows 
programs. But between the call to cre¬ 
ate the Ddshell window and the mes¬ 
sage loop are two calls that are perhaps 
not so familiar, GetSystemMenu() and 
AppendMenuf). Since Ddshell runs only 
as an icon, it cannot have a menu bar, 
so it is the system menu that is dis¬ 
played when you click on the icon. To 
add an item, Ddshell gets a handle to 
the system menu (returned by Get- 
SystemMenu()) and then uses Append- 
Menu () to append a separator line and 
an “About” item. The ID number of an 
appended item (which is the third argu¬ 
ment to AppendMenuO) must be lower 
than F000H to avoid conflicts with ID 
numbers used by Windows. Ddshell 
uses a value of 1, which is defined by 
IDM_ABOUT. The icon is made visible 
with a call to ShowWindow, then is posi¬ 
tioned according to initial position 
values obtained from the Ddshell.ini 
file. The title is also based on a value 
from the .ini file. The initial position 
and title variables are set when the 
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Listing 1 continued 


initialYPos = GetPrivateProfilelnt 

(lpDDInstance, “yPos", 0, "ddshell.ini"); 
DragAcceptFiles (hWnd , TRUE ); 
return 0; 

case WM_M0VE: 

xPos « (int) L0W0RD (IParam); 
yPos = (int) HIWORO (IParam); 
wsprintf (szString, "%i", xPos); 

WritePrivateProfi1eString 

(lpDDInstance, "xPos", szString, “ddshell .ini K ) ; 
wsprintf (szString, "%i", yPos); 

WritePrivateProfi1eStri ng 

(lpDDInstance, ''yPos", szString, "ddshell.ini"); 

return 0; 

case WM_DROPFILES: 

hDrop = (HDROP) wParam; 

TotalNumberOfFiles = DragQueryFile( hDrop , OxFFFF, NULL, 0 ); 
for ( 1 » 0; 1 < TotalNumberOfFiles ; i++ ) 

( 

len = DragQueryFile( hDrop , i , NULL, 0 ); 
if (len > MAXPATH) 

{ 

wsprintf (szString, 

"The path for dropped file %i is to long", i); 
MessageBox(hWnd, 

szString, szAppName, MB_ICONEXCLAMATION | MB_0K); 

) 

else 

{ 

DragQueryFile( hDrop , i, szFileName, MAXPATH + 1 ); 
wsprintf (szString, 

"%s %s", (LPSTR) szCommand, (LPSTR) szFileName); 
winExecErr = WinExec (szString, SW_SHOW); 
if (winExecErr < 32) 

( 

switch (winExecErr) 

{ 

case 2: 

wsprintf (szString, 

"Invalid command path:\n%s", 

(LPSTR) szCommand); 
break; 
default: 

wsprintf (szString, "%s %s %s\n%s %d", 
(LPSTR) "Error launching command:' 1 , 
(LPSTR) szCommand, (LPSTR) szFileName, 
(LPSTR) "error code =", 
winExecErr); 

) 

MessageBox (hWnd, szString, szAppName, 

M8_ICONEXCLAMATION | MB_0K); 

} /* end if (winExecErr < 32) */ 

) /* end if (len > MAXPATH) */ 

) /* end for ( i = 0; i < TotalNumberOfFiles ; i++ ) */ 

DragFinish( hDrop ); 
return 0; 

case WM_SYSCOMMAND: 
switch (wParam) 

{ 

case IDM_AB0UT: 

wsprintf (szString, "%s%s%s", 

(LPSTR) "Drop and Drag Shell\n", 

(LPSTR) " version 2.0\n", 

(LPSTR) "(c) Noah Davids 1992"); 
MessageBox(hWnd, szString, szAppName, 

MB_ICONEXCLAMATION | MB_0K); 


UM_CREATE() message is processed by 
the UndProc() procedure. Windows 
sends the UM_CREATE() message direct¬ 
ly to the UndProc procedure as a non- 
queued message, so that it can com¬ 
plete before UinMain has set up its 
message loop. 

The UinProcf) procedure is a giant 
switch statement that processes the 
messages that Windows sends to 
Ddshell. The first case in the switch 
statement processes the UM_CREATE 
message, and the first thing that it does 
is check that a section name was 
provided as a command-line argument. 
A pointer to a string containing the 
command-line arguments is passed as 
the third argument to the UndMainf) 
procedure. In order to get the value of 
that pointer to the UndProc () proce¬ 
dure, UndMainf) assigns it to the exter¬ 
nal variable lpDDInstance. UndProc() 
checks the length of the string: if the 
length is zero, then no section name ar¬ 
gument was provided, so an error is 
reported and the window is destroyed. 
The check is done here rather than in 
the UndMainf) procedure because by 
this time Windows has allocated a win¬ 
dow handle for Ddshell that can be 
used in the call to MessageBox. 

The UM_CREATE code next reads the 
Ddshell.ini file for initial values by 
calling GetPrivateProfileString() 
twice to read the command path and 
the title and calling GetPrivate¬ 
Profilelnt () twice to read the x and 
y positions. Note that it uses the com¬ 
mand-line argument string pointer, 
which points to the section name, as 
the first argument in these calls. For 
both GetPrivateProfileStringf) and 
GetPrivateProfilelnt() , the third 
parameter is a default value-, in the call 
to read the command line, the default 
is a null string. If the value returned is 
also a null string, then either the . ini 
file was not found, the section was not 
found in the . ini file, or the section did 
not have a command entry. For any of 
these cases an error is reported and the 
window is destroyed. 

GetPrivatePrifileStringf) will al¬ 
ways append the null character to the 
end of the string that it copies to the 
buffer. This means that an N character 
buffer will contain at most N-1 charac¬ 
ters from the entry. Unfortunately, since 
the count of characters copied — which 
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break; 


is the function's return value —does not 
include the null character, it is impos¬ 
sible to tell whether or not an N-l 
return value means that the entry was 
truncated. Ddshell uses a buffer size of 
MAXPATH + 2 characters for the com¬ 
mand and 80 characters for the title. 

MAXPATH is defined in the dir.h header 
file as the maximum length of a DOS file 
path: MAXPATH + 2 is thus large enough 
to hold a MAXPATH + 1 string plus the 
terminating null character. A returned 
count greater than MAXPATH therefore 
means that the entry is too long, and 
so Ddshell will report an error. By trial 
and error I found that 79 characters is 
the maximum that Windows will use 
for a window title. If the title is too 
long, the truncated version is used. 

The last thing that the UM_CREATE case does is tell Win¬ 
dows that Ddshell is ready to accept dropped files. It does this 
by calling DragAcceptFiles() with the first argument set to 
the handle of the Ddshell window and the second argument 
set to TRUE. 

The code processing the WM_M0VE message also deals with 
the . ini file. In this case it writes to the . ini file instead of 
reading from it. Windows sends a HM_M0VE message to a win¬ 
dow after it has moved the window or icon to a new location. 
The message contains the x and y position of the upper-left 
corner of the window or icon. Ddshell extracts the x and y 
positions from the message, converts them to strings, and 
then writes them into the Ddshell.ini file (the position 
values must be converted to strings because there is no 
WritePrivateProfilelntO function). You’ll notice that the 
last thing that the UM_M0VE message code does is call Urite- 
PrivateProfileStringO with most of its arguments set to 
null. Windows caches the last few private . ini entries that it 
has read or written. This means that the entries just written 
are not really output to the . ini file. Instead Windows stores 
them in memory to be output to the . ini file when Windows 
terminates or when different. ini entries are read or written. 
Just to be safe, this final call to UritePrivateProfile- 
StringO forces Windows to output the entry values to the 
. ini file. 

When a file or group of files is dropped on a window, Win¬ 
dows sends the window a WM_DROPFILES message. In general, 
when an application receives this message, it first makes a 
call to DragQueryFileO to learn how many files were 
dropped. It then enters a loop and again calls DragQuery- 
Fi le(), first to get the length of the string containing the path 
of one of the files dropped and then again to get the actual 
string. It is not necessary to make the call that returns the 
path length, but if the path is longer than the buffer provided, 
Windows will truncate it As is the case with GetPrivate- 
ProfileStringO, the length value returned does not include 
the null terminating character, but unlike GetPrivate- 
ProfileStringO, if Windows is forced to truncate the path, 
then the last character in the buffer will not be a null charac¬ 



return 0; 


case WM_CL0SE: 

DragAcceptFiles( hWnd , FALSE ); 
break; 

case WM_DESTR0Y: 

PostQuitMessage(O); 
return 0; 

) 

return DefWindowProc(hWnd, message, wParam, IParam); 
} /* end of WndProc */ 

/* End of File */ 


ter. After exiting the loop but before leaving the WM_DROPFILES 
code, the DragFinish() procedure must be called. 

The code that processes VM_DROPFILES messages in Ddshell 
follows this pattern. The first call to DragQueryFiles() uses a 
file index of OxFFF, which tells Windows to return the number 
of files dropped. The next call to DragQueryFiles() gets the 
string length, after which the string length is tested to make 
sure it does not exceed the buffer size. Two important points 
must be noted here. First, the first dropped file has an index of 
0, so the loop index goes from 0 to (TotalNumberOfFil.es - 1). 


TCP/IP 
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middleware API for encapsulated 
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► New Evaluation kit available 
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Listing 2 

ddshell.rc 
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Second, the path length must be less than the buffer size so 
that there is space for the terminating null character. The 
buffer should always have enough room because it is based 
on the current DOS limit, but since that limit may change, a 
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length check now may prevent bugs in the future. If a length 
problem occurs, it is reported and the file is not processed. If 
the file path is returned without error, the command-line 
string formed by concatenating the command path and the 
dropped file path is then executed with the UinExecQ call. If 
UinExec() encounters an error, it returns a value less than 32 
and reports the error. 

When an item from the system menu is selected, Win¬ 
dows sends the window a UM_SYSCOMMAND message that con¬ 
tains the ID of the item selected. Since Ddshell adds an 
“About" item with an ID of IDM_ABOUT to the system menu, it 
must check to see if this item was selected. In accord with 
my “keep it simple" approach, the “About” message is dis¬ 
played with a MessageBox. If any other system menu item 
was selected, the code will fall through to the end of the 
procedure, where the message is passed on to the default 
window message handler. 

The last two messages deal with closing Ddshell. The 
UM_CLOSE message is sent when the application is closed. 
Ddshell informs Windows that it is no longer willing to process 
dropped files by calling DragAcceptFiles(), this time with the 
second argument set to FALSE. It then falls out of the switch 
statement and calls the default window message handling 
procedure to handle any other details that the UM_CLOSE mes¬ 
sage may require. The UM_DESTROY message is the last mes¬ 
sage that Windows will send to an application. The code posts 
a quit message which causes the 6etMessage() call at the top 
of the message loop in UinMainf) to return FALSE and ter¬ 
minate the message loop. This in turn allows the Ddshell to 
finish execution and terminate. 

Conclusion 

If, like me, you see a use for drag-and-drop with applica¬ 
tions that do not support it, Ddshell can supply it o 
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Converting Ticks to Time 


Murray L Lesser 


The heartbeat of the PC, the BIOS timer “tick," beats at the inconvenient rate of 
approximately 18.2 times per second. There comes a time in every PC programmer’s 
life when it is necessary to convert the BIOS timer tick count to a time of day, in a 
format suitable for calculating small elapsed times. Although it is only an approxima¬ 
tion, 18.2 ticks per second is probably the most popular approximation used in such 
calculations. For example, Borland C compilers use it for the value of CLK_TCK, the 
implementation constant used with the Standard C clock function to measure a 
time interval nobody cares about: the approximate interval since the program 
started running. 18.2 ticks per second corresponds to 1,572,480 ticks per 24 hours, 
and it turns out that this approximation gets to midnight about 30 seconds before 
the DOS clock does. A better approximation, sometimes used, is 65,536 ticks per 
hour, or 1,572,864 ticks per day. This approximation gets to midnight only about 10 
seconds before the system clock should. But why use an approximation? You can 
easily compute the exact conversion with a small assembly language function. This 
article shows you how. 

On all IBM PC's, PS/2's, and compatibles the BIOS resets the timer count (a long 
integer at address 0040:006c) to zero when the count reaches 1,573,040 ( 1800b0h ), 
marking PC midnight. The BIOS sets the “midnight overflow flag" to 1 at 
the same time, to be available to DOS the next time the operating 
system requests the time of day or date. (DOS can be fooled by 
programs that use BIOS INT lAh, ah=0, to read the BIOS timer count; 
that interrupt was designed for operating-system use only, and resets 
the overflow flag when it is used.) The value of 1,573,040 ticks per 24 
hours (shown in the BIOS listings in early IBM PC Technical Reference 
manuals) is derived directly from the PC system timer design, using the 
nominal input frequency of 1.19318 MHz with a divisor of 65,536. 

It is not difficult to compute the equivalent time of day — in 
hundredths of a second since PC midnight - directly from the 32-bit 
timer count, as shown in hunsecs.asm (Listing 1). As shown, hunsecs is 
written to be linked to compiled BASIC programs, but it is not difficult 
to edit the listing for use with any high-level language implementation 
conforming to the Microsoft mixed language return conventions. As 
does BASIC's TIMER function, hunsecs mimics the DOS clock in that it 
returns a value to a precision of 0.01 second, even though its actual 
resolution is only about 55 milliseconds. Unlike TIMER, hunsecs can be used to time 
intervals to that precision without using floating-point arithmetic. 


Murray L Lesser received a BS degree in Engineering from CalTech in 1942 and 
earned his living as a programmer until 1954, when he joined IBM to work in 
what would become “systems architecture" (but claims no responsibility for the 
IBM PC, having retired before it was announced). He has been programming 
microcomputers and writing books and articles about the subject since 1979. 


December 1992 


Windows/DOS Developer’s Journal — Page 67 
















The code reads the two-word timer count with a single 
instruction to avoid having to disable interrupts. This approach 
also avoids the around-midnight calendar hazards of calling 
INT lAh, ah-0, ("Read BIOS time") from any source other than 
the operating system. 

The actual conversion consists of multiplying the timer 
count by (100 * 65,536) and then dividing by 1,193,180. Since 
the 32-bit quotient will be returned in the register pair DX:AX, 
multiplying by 65,536 is accomplished by moving the high 
word of the quotient to DX. If you divide both the remaining 
numerator (100) and the denominator by 20, you can perform 
the entire 32-bit operation with 16-bit register arithmetic. The 
listing comments should be sufficient to describe the rest of 
the algorithm. 


Figure 1 

Output of tryit.bas at midnight 
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Windows DLLs 


Now you can write your communication and UNIX screen 
applications under Windows. Our libraries support dynamic linked 
library interfaces for Microsoft 7.0 and Borland 3.1, or any Windows 
language. Libraries include object, example programs, and 
documentation. Source is optional at an additional charge, No royalties. 

CrystalCOMM for Windows $175 

CrystalCOMM is a communications library written in C for the 
Windows environment It supports the development of modem or serial 
port communication programs. It includes everything to maintain 
consistency in the Windows foreground or background environment and 
includes DLL support. CrystalCOMM supports XMODEM, XMODEM- 
CRC, YMODEM, YMODEM-G, ZMODEM, KERMIT, and ASCII 
communication protocols through a simple, structured function 
interface. Supports both packet or file calls, KERMIT get command, and 
8-port DigiBoard. Can support up to nine simultaneous ports. Examples 
in C, Turbo Pascal, and Visual Basic. Also under DOS for $125. 

Crystal CURSES for Windows $175 

Crystal CURSES for Windows is a UNIX SYSTEM V CURSES 
compatible library for the Windows environment. It helps you to move 
your UNIX CURSES based application to the Windows environment 
without rewriting the screen interface to comply with the Windows 
GUI, Crystal CURSES includes support for dynamic linked library. The 
functionality of CURSES in the Windows environment is expanded to 
include Font and Dialog control. Complete UNIX V implementation. 
Crystal CURSES is available under DOS in compatible form for $125. 
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tryit.bas (Listing 2) is a demonstration driver illustrating 
the use of hunsecs to build a delay loop and also comparing 
the result directly with the output of the DOS clock converted 
to seconds-and-hundredths (the BASIC TIMER function), tryit 
also illustrates one way to take care of timed events that may 
cross PC midnight: making sure you don't get into an endless 
loop by trying to compare to a time after the last tick before 
midnight (8639994 hunsecs). A sample run of tryit, across 
midnight, is shown in the Figure 1. □ 


Listing 1 hunsecs.asm - Return time of day in 
hundredths of a second 


.model medium 

*********************************************************************** 

HUNSECS.ASM 

HUNSECS [DECLARE FUNCTION HUNSECS& ()] Is an assembled function for 
compiled BASIC programs. HUNSECS reads the BIOS timer count directly 
(not using INT 1A so as not to reset the timer overflow flag), and 
returns the system time of day in hundredths of seconds as a long 
integer. It serves the same timing purposes as does the intrinsic 
BASIC function "TIMER" without requiring floating-point arithmetic. 

Copyright (C) 1992 by Murray L. Lesser 


.code 

public 

hunsecs 


hunsecs 

proc 




push 

bp 

;For safety's sake - no arguments 

passed 

mov 

ax,40h 

jTimer count Is dword at 40:6c 


mov 

es.ax 



les 

cx,es:[6ch] 

;T1mer count now In ES:CX 


mov 

ax.es 

;H1gh word of timer count 


mov 

bx,5 

; (maximum value Is 18h) 


mul 

bx 

;Product still in AX, DX holds zero 


xchg 

ax.cx 

;Low word of count now In AX 


mul 

bx 

; (high word of product in CX) 


add 

dx.cx 

;Count * 5 * 65536 in DX:AX 


mov 

bx,59659 

;1193180/20 


div 

bx 

;Remainder in DX, 


mov 

cx,ax 

;H1gh word of quotient In CX 


xor 

ax,ax 



div 

bx 

;Low word of quotient in AX 


mov 

dx,cx 

;Time of day in hundredths now in DX:AX 


pop 

bp 



ret 




hunsecs endp 
end 

; End of File 


Listing 2 tryit.bas - BASIC Demonstration of 
hunsecs.asm 


' TRYIT.BAS - A demonstration driver for the hunsecs function module 


Compiled with BC 7.1, 
' Linked to hunsecs.obj 

declare function hunsecs&() 
dim now as long, old as long, 1 as 

print: print " Hunsecs", " Timer" 
print 

for 1 « 1 to 10 

let old * hunsecs 
let now = old + 130 
' Correction if delay crosses last 
if now > 8639994 then 

while hunsecs >= old: wend 
if now < 8640000 then 
let now = 0 

else 

let now = now - 8640000 
end if 
end if 

while hunsecs < now: wend 
print hunsecs, timer 

next 


switch "/o" 

with LINK 5.13, switch "/e" 


Integer 


'Start of delay loop 
'A 1.3-second delay loop 
tick before midnight 
'If delay crosses last tick In day 
'Wait until midnight 
'If now Is in last tick 
' set It to zero 
'Else correct for next day 
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Binding for Real-Mode Execution 

Ed Rosenblatt 


This article shows you how to use a “bind" to produce an 
executable load module capable of executing in either real or 
protected mode —a file of the type designated by Microsoft as 
a “bound executable.” (In fact, before version 7.0, Microsoft C 
came with two subdirectories for executables, bin and binb; 
binb contained “bound" executable files capable of running in 
real and protected mode.) The Phar Lap 286|DOS-Extender al¬ 
lows you to create a module that can run in real-mode DOS, 
protected-mode DOS, Windows enhanced mode, and 
protected-mode, character-based OS/2. I have confirmed this 
by loading the exact same module in protected-mode DOS, 
real-mode DOS, and in a resizeable window in Windows 3.0 
and 3.1 enhanced mode. I haven’t tried character-based OS/2. 
In protected-mode DOS and Windows, I had access to all the 
extended memory on the machine. In real-mode DOS, I could 
only access conventional memory. 

Binding replaces the default real-mode stub in a seg¬ 
mented executable file, but does not necessarily produce a 
real-mode module. This article focuses on the techniques used 
to create a dual-mode (protected and real-mode) module. The 
bind used to create a dual-mode module 1 will call a real¬ 
mode bind, to distinguish it from a bind that accomplishes 
other tasks. 



Why Dual-Mode Support? 

My interest in supporting both real-mode protected-mode 
programs stems primarily from the fact that our user base is 
split between desktop users with 386-SX machines with 2 
meg of RAM and portable users with Toshiba 1000-SE's, which 
use an 8086 chip. To ignore that 1Mb of extended RAM would 
be foolish. Our desktop environment has LAN drivers and 3270 
emulation drivers, all of which eat up precious conventional 
memory and leave little room for our application. Also, our 
system will continue to dynamically allocate memory in order 
to satisfy users’ requests until there is no more allocatable 
memory. The default configuration of Phar Lap loads in ex¬ 
tended memory and leaves a small footprint in conventional 
memory. You can then keep allocating memory until there is 
no more extended memory left. On most 386SX machines, 
this usually gives a comfortable 1Mb of extended accessible 
memory. 

Developing in protected mode also offers more memory 
protection than developing in real mode. Memory overwrites 
are caught by the hardware, which generates an exception 
that a protected-mode debugger (such as the protected-mode 
CodeView) can use to point you to the instruction that caused 
the exception. I wish I could say that every condition that 
could cause your machine to hang is caught in protected- 
mode, but that just isn’t the case. For instance, since your 
automatic variables are on the stack, and the stack is imple¬ 
mented as a single segment, you can still overwrite automatic 
variables and cause problems which will not be caught by the 
hardware. 

Given the choice, I prefer to develop, test, and debug in 
protected mode even if I am not running the resulting applica¬ 
tion in protected mode. I can accomplish this by using a real¬ 
mode bind. 

Segmented Executable Files 

One way of producing a protected-mode program is to use 
a DOS extender. The DOS extender sets up the protected- 
mode environment and handles the interface to DOS, inter¬ 
cepting all your INT 21h calls and transforming them to real 
mode for DOS (DOS is inherently limited to real-mode opera¬ 
tion). To produce a protected-mode program, you need to cre¬ 
ate a segmented executable file. 


Ed Rosenblatt is an independent consultant who specializes in software development He has been developing in-house applications 
for ABC News for eight years. This article is based on an application developed there which runs on both 80386SX and 8086 
machines. You may contact him at Third Wave, Inc, 342 Brook Ave., Passaic, NJ 07055. 
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Listing 1 


linclude <dos.h> 

// Parameters are passed in through a structure, 
void set_pos(struct set_pos *pos) 

{ 

union REGS regs; 

// The Microsoft register structure is used 
// to load parameters. 

regs.h.ah = 0x02; 
regs.h.bh « pos->page; 
regs.h.dh ■ pos->row; 
regs.h.dl = pos->co1; 

// The int86 instruction is issued. 
int86(0xl0, Sregs, &regs); 

return; 

) 

/* End of File */ 


Using a segmented executable linker, you can create a seg¬ 
mented executable file, or “new .exe” file. The format of 
these files is identical for OS/2 and Microsoft Windows, and is 
a superset of the “old .exe" format for a real-mode load 
module. The linker supplied with Microsoft C versions 5.1 and 
later is a segmented executable linker. 

These files are significantly more complicated than the old 
style real-mode load modules. They include support for real¬ 
mode execution, protected-mode execution, and external 
routines imported from Dynamic Link Libraries (DLLs). DLLs are 
segmented executable files that are linked with the seg¬ 
mented executable linker using a definition file to describe 
routines that are to be exported from the DLL. 

These segmented files also contain a real-mode stub. It is 
this stub that helps give these files the flexibility to execute in 
real mode. The default real-mode stub displays an error mes¬ 
sage and terminates a protected-mode program, since this 
program cannot normally execute under DOS. It is possible, 
however, to prepare this program for real-mode execution. 
This bit of magic is accomplished with a "real-mode bind.” 

DOS Extenders 

Since DOS is inherently limited in its ability to take ad¬ 
vantage of the features added to the 286 and 386 architec¬ 
ture, a different operating environment is needed. My ex¬ 
perience is with Phar Lap’s 2861 DOS-Extender. Operating in 
protected-mode allows access to all extended memory, offers 
greater memory protection, and allows you to use DLLs. Under 
this environment, programs are produced using a combination 
of OS/2 libraries, protected-mode libraries, and vendor-supplied 
libraries. The "Family API” (FAPI) of OS/2 calls is allowed, as well 
as vendor-supplied routines needed to operate in the richer 
environment. The resulting executable cannot be executed 
directly under DOS. 

Binding 

Binding a module replaces the default real-mode stub with 
a new stub. This replacement stub can also be specified in a 


definition file at link time. For example, the real-mode stub 
that Windows programs generally use simply prints out an 
error message informing the user that this executable must 
be mn from Windows. 

With the Phar Lap 2861 DOS-Extender, you would typically 
use their bind command ("bind286”) to replace the default 
real-mode stub with a program called gorun286. gorun286 in¬ 
vokes run286, which is Phar Lap’s protected-mode loader. 
run286 sets up the protected-mode environment and loads 
and executes your protected-mode code. 

In order to produce a program capable of executing in real¬ 
mode, you must perform a real-mode bind, which is consider¬ 
ably more complicated than the bind described above. Not 
only must it replace the default real-mode stub (remember 
that the default stub merely puts out a message that your 
program cannot be run in real mode), but it must also resolve 
any module references from DLLs, do something with all the 
protected-mode code that is in your program, and add a 
routine for each FAPI OS/2 routine used. This will produce a 
module which is executable in real mode directly under DOS 
as well as protected mode. The Microsoft bind utility can ac¬ 
complish this. 

Dual-Mode Development 

There are at least two ways to approach dual-mode 
development. The first way is to use the preprocessor to con¬ 
trol, at compile time, whether you are compiling real-mode or 
protected-mode code. If you choose this method, you do not 
need to use a bind to produce a real-mode program and you 
can link with the real-mode libraries. However, you are not 
creating a dual-mode program-, instead, you would have two 
executable modules, one for real-mode execution, and the 
other for protected-mode execution. What I like even less, 
though, is that this method requires you to keep track of all 
routines that have protected-mode code. You must recompile 
them separately, depending upon the module you are going 
to produce, and keep track of the object modules in separate 
subdirectories or libraries. Depending upon the size of your 
system, this can create a maintenance nightmare. 

The second method, and the one I chose, is to use runtime 
checking to distinguish between real and protected mode. 
With this method you produce a dual-mode module and dis¬ 
pense with preprocessor defines. Your runtime checking tells 
you what environment you are in, and allows you to execute 
code conditionally, depending on whether you are in real 
mode or protected mode. This greatly simplifies maintenance. 
Source modules with dual-mode code do not have to be 
recompiled; they enter the executable with identical code. 
You can bind the executable and produce a dual-mode 
module. 

Runtime Checking for Protected-Mode 

Runtime checking for protected mode execution is trivial. 
The Microsoft libraries supply a variable called osmode. The 
check is as simple as the following code fragment: 
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if (_osmode == MODE_PROTECTED) { 

} 

else { 

} 

If the environment is protected-mode, any protected-mode 
specific code is executed, otherwise the real-mode code is ex¬ 
ecuted. A classic and simple example of this is the following: 

if (_osmode == M0DE_PR0TECTED) 

DosMapRealSeg(0xB800, 

32768, &g.vid_seg_addr); 

else 

g.vid_seg_addr = 0xB800; 

This sets up the environment for direct screen writes. In 
protected mode, you need an alias segment to address seg¬ 
ment B800h-, in real mode you can address it directly. 
g.vid_seg_addr is declared in a global structure as an un¬ 
signed int, and is used as the segment portion of a far 
pointer to the video buffer. DosMapRealSegO is a Phar Lap API 
function that sets up an alias segment to the segment re¬ 
quested, creating a protected-mode selector and inserting the 
selector in the variable instead of the actual segment address. 
The code illustrated is conditionally executed depending upon 
what mode you are executing in. You can use this style of 
runtime checking to handle all the mode-specific portions of 
your code. 

The Bind 

Before looking at the actual bind syntax, it is helpful to 
understand more specifically what must be done in order to 
prepare your module for real-mode execution. The first thing a 
bind does is substitute the default real-mode stub with a 
suitable loader for real-mode execution. Next, there are poten¬ 
tially many subroutine calls the real-mode bind must handle. 
These fall into three categories: 

• FAPI OS/2 calls 

• Subroutines in DLLs 

• Protected-mode routines not supported in real mode 

The first two are fairly easy to deal with, since the bind is 
designed to remap the FAPI calls into MS-DOS or ROM BIOS 
function calls and to resolve subroutine alls from DLLs. In a 
protected-mode program you can make calls to routines that 
are imported from DLLs. The executable only has a reference 
to the subroutine. In the case of a protected-mode program, 
DLLs get loaded at program load time. The real-mode bind has 
to seek out these routines and include them in the ex¬ 
ecutable. The bind accomplishes both of the above functions 
by referencing the FAPI library and the relevant DLL libraries. 

The third case —protected-mode routines that are not sup¬ 
ported in real mode —presents more difficulties. Before seeing 
how these routines are handled, look at the actual bind syn¬ 
tax: 


BIND infile [file.lib ...] [file.obj ...] [options] 


Infile” is the segmented executable file with the default ex¬ 
tension of .exe. “file.lib” is one or more API or DLL libraries. 
You have to specify these libraries explicitly because the bind 


Listing 2 


♦include <dos.h> 

// Parameters are passed in through a structure, 
void set pos(struct set pos *pos) 

( " 

unsigned char page; 
unsigned char row; 
unsigned char col; 

// Pointer to structures are not accessible in 
// in-line assembler... load local varaibles. 
page = pos->page; 
row = pos->crow; 
col - pos->ccol; 

// Drop into assebler to load registers and issue 
// interrupt. 

_asm 

I 


mov 

ah, 

2 

mov 

bh. 

page 

mov 

dh. 

row 

mov 

dl, 

col 

int 

0x10 


I 

return; 

) 

/* End of File */ 
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utility does not search the path specified in the “LIB” environ¬ 
ment variable. You can also explicitly reference any .obj you 
want to link into your module. Using these libraries and object 
files, the bind resolves all the modules in the DLLs and addi¬ 
tional real-mode versions of the FAPI routines. 

To handle routines specific to protected mode such as Dos- 
MapRealSegO (presented earlier), you must use the bind op¬ 
tions. The options are as follows: 

/o outfile 
/n name(s) 

/n @filename 
/m 

“outfile” specifies the name of the output . exe (the default is 
the same as input .exe). /m instructs the bind to produce a 
map file with a default name of outfile.bm. 

The remaining two parameters handle the protected-mode 
code. Using In, you specify the names of the functions that 
only run in protected mode (if you wish, you can enter the 
names of all these routines in a file, and specify the file's 
name using the Qfilename syntax). You must include the 
names of all the protected-mode functions that you call when 
running in protected mode. The bind then replaces calls to 
these functions with calls to BadDynLinkf), which simply dis¬ 
plays an error message. Of course, if you have done the run¬ 
time checking with _osmode correctly, you will never hit this 
routine, since you will only call protected-mode functions 
when you are running in protected mode. After a successful 
bind of your protected mode program, you have a program 


capable of running in protected-mode and real model Well... 
maybe. 

Interrupt Code 

Depending on how you have written your code, you may 
in fart now have that magical dual-mode module. I ran into 
some additional problems. I performed all my BIOS calls by 
calling int86(), as the example in Listing 1 shows. This func¬ 
tion (along with similar functions such as intdos()) is not in 
the Microsoft protected-mode libraries, which implies that 
these routines as written will not work correctly in protected 
mode. Phar Lap supplies substitute routines with the same 
name in their protected-mode libraries, but these routines are 
only for protected mode and are not compatible with real¬ 
mode execution. It is easy, however, to rewrite these BIOS 
calls with inline assembler, as shown in Listing 2. These calls 
are now compatible with real- and protected-mode execution. 

Critical Error Handler 

This problem was a bit trickier to detect and solve. I 
originally wrote my critical error handler using the Microsoft C 
functions _harderr(), _hardretn(), and _hardresume(). 
There are no hardware error routines in the Microsoft 
protected-mode libraries, and Phar Lap supplies replacement 
routines for only two of the three routines. I wrote the 
protected-mode critical error handler using the Phar Lap API. 
For real-mode critical error handling, I decided to extract the 
_harderr() routine from the real-mode libraries, like this.- 

lib 11ibee *_harderr, 11ibee.1st; 


More on 

One of the problems encountered by developers using 
Microsoft C v5.1 and C v6.0 is that the compiler runs out of 
far heap space for any nontrivial source file. This leads to 
numerous kludges, including the use of manifest constants 
to exclude parts of the huge windows.h header file (function 
prototypes are particularly notorious for eroding this valu¬ 
able memory resource). However, since the C5.1 and C6.0 
executables are all dual mode (that is, they can run under 
protected mode or real mode), and since protected mode 
does not impose a 640Kb limit on far heap space, getting 
your executables to run under protected mode is a 
worthwhile endeavor. 

When you installed C5.1 or C6.0, you were asked if you 
wanted a real-mode host (DOS) and also if you wanted a 
protected -mode host (OS/2). If you chose both, some of the 
executables will be dual-mode executables. The dual-mode 
executable is actually a protected-mode executable that 
uses Microsoft's New Executable (NE) format. This executable 
contains a real-mode stub. For these dual-mode executables, 
the stub is actually the real-mode version of the particular 
tool. But if you run the executable in protected mode, you 
get the protected-mode version of the program. 

Enter the DOS extender. In particular, Phar Lap’s 286|DOS- 
Extender can be used to provide a protected-mode environ¬ 
ment to an executable. The command run286 cl runs the 


Binding 

compiler in protected mode, but you can also use Phar Lap’s 
bind286 utility to replace the real-mode stub of any NE file 
with a little utility that first loads the DOS extender, then 
transfers control to the program. After binding an executable 
(and placing the location of the Phar Lap 2861 DOS-Extender, 
run286.exe, in your PATH environment variable), the ex¬ 
ecutable will come up in protected mode by default, so the 
“run286" preface is not required. 

But this is not the end of the story. Microsoft's latest 
compiler, C v7.o, runs in protected mode as long as the DOS 
memory manager is a DPMI server (such as Qualitas's 
386MAX Version 6 that comes with C v7.0). This is great 
news since you no longer have to buy a DOS extender to 
run the compiler. Alas, Microsoft did not build the same 
technology into the Windows resource compiler, so if your 
program has a large resource file, you still need a solution 
like the Phar Lap 2861 DOS-Extender. 

To bind the resource compiler: 

• Install the Phar Lap 2861 DOS-Extender and put the directory 
containing run286.exe in your PATH environment variable 

• Execute the command bind286 rc.exe. This replaces the 
real-mode version of RC with the DOS extender loader. 

The result is a resource compiler that you can finally use 
under Windows without running out of memory. □ 

—Paul Bonneau 
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harderrf), however, calls other low-level routines that are 
mode-specific These routines are used by compiler routines in 
both modes, but they use preprocessor defines for determin¬ 
ing environment and cannot be executed in both real and 
protected mode. Thus, I would have to link my program twice 
—once without the low-level routines for protected mode, and 
once with the routines for real mode. I would still not have to 
recompile my dual-mode routines, but I would not have 
achieved the goal of a dual-mode module. 

There are two ways to solve this problem. The first is to 
use the _dos_getvect() and _dos_setvect() routines, which 
do not all mode-specific routines. Since the routines do not 
exist in protected-mode, you must still extract these modules 
from the real-mode library, then manually link them into your 
module. The following code fragment shows the code needed 
to install either the protected-mode critical error handler or 
the real-mode critical error handler: 

if (_osmode == MODE_PROTECTED) 
DosSetPassToProtVec(0x24, 
new_crit_err_hnd, 
old_crit_err_prot, 
old_crit_err_real); 
else { 

old_crit_err_hnd = _dos_getvect(0x24); 
_dos_setvec(0x24, new_crit_err_hnd); 

} 

This approach results in a module that, after the bind, is truly 
dual-mode and can be executed in real or protected-mode. 

There is another, perhaps cleaner, way to solve the prob¬ 
lem, but the module it generates exhibits slightly different be¬ 
havior in its handling of critical errors in real mode and 
protected mode. This solution entails using the FAPI routine 
DosError(). The call is simple: 

Dos Error(0x0000); 

The result proved to be fascinating. DosError() is apparently 
not compatible with the Phar Lap protected-mode environ¬ 
ment since it is an OS/2 routine. Remember, however, that 
the bind will replace FAPI routines with suitable real-mode 
DOS routines, and this exactly what happens. However, it now 
adds a feature to DOS that DOS itself does not have. By calling 
Dos Error () with 0x0000, you disable the operating system's 
ability to handle the critical error; as a result, it returns to 
your program with a DOS error. If you erroneously try to ac¬ 
cess a file on a:, DOS will magically return a DOS error to your 
program instead of producing the familiar “Abort, Retry, Fail" 
message! You can now install your critical error handler as 
above, except that you use Dos Error () for the real-mode 
critical error handling. There is no need to manually link in a 
real-mode routine, and you again have a fully dual-mode 
module after the bind. 

Program Name 

Having finally succeeded in creating this dual-mode pro¬ 
gram, I ran into one more problem. A particular function in 
our system displays the attributes of the load-module: the ex¬ 


plicit name, size, and link date. I noticed that when my real¬ 
mode program got control, argv[0] did not contain the full 
name with path and suffix, but contained only the program 
name without path or suffix. I phoned Microsoft and con¬ 
firmed that the real-mode loader, which is bound to the 
protected-mode program, strips the path and suffix from the 
load module name when passing it into your program. For¬ 
tunately, there is a very simple solution to this problem. The 
variable _pgmptr is declared in crtOdat.asm, which is part of 
the startup code for your C program. The variable is declared 
as external, so your program can declare it as 

extern char _far *_pgmptr; 

and reference it This variable is a pointer to a character string 
that contains the full name of the program with the path. 

Conclusion 

Using the above techniques, you can produce a program 
which will run in real-mode, DOS-extended protected-mode, 
Windows 3.0 and 3.1 enhanced mode, and OS/2 character- 
based mode. You could load the module in any of the 
protected modes and have full use of all available memory, 
yet still be able to execute this module on an 8088. □ 
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continued from page 36 


Premia Ships Codewright v2.0 

Codewright is a programmer's editor designed from the 
ground up to operate efficiently under Windows. Version 2.0 
includes text drag and drop, configurable ribbon and toolbox, 
GHU CTags support, word wrap and paragraph formatting, 
spell checking, hierarchical file find and file grep, and DDE 
support The new version also adds language templates and 
ChromaCoding support for Clipper/xBASE to the existing sup¬ 
port for C, Pascal, PAL, and assembly language. 


Codewright v2.0 costs $249 for a single-user license and 
comes with an unconditional 30-day money-back guarantee. 
Multiuser and LAN licenses are also available. For more infor¬ 
mation, contact Premia Corporation, 1075 NW Murray 
Blvd., Suite 268, Portland, OR 97229, (503) 647-9902 or 
(800) 547-9902; FAX (503) 647-5423; CIS 70673,2627. 


GCP++ SDK Eases TCP/IP Programming 

GENISYS Comm, Inc, has introduced the GCP++ Develop¬ 
ment Pack, a Winsock-compatible Windows 3.1 DLL that 
provides encapsulated access to TCP/IP networks. GCP++ lets 
you write complex, cooperative network applications 
without dealing with socket libraries and remote procedure 
call conventions. GCP++ supports encapsulated Tel- 
net/TCP/UDP access, task-to-task communications, file trans¬ 
fer, and packetized voice between multimedia PCs. 

You use function calls to initiate communication service. 
The using application specifies a remote IP address and the 
type of communication server required (encapsulated Tel- 
net/TCP/UDP or GCP). The Telnet, TCP, and UDP servers pro¬ 
vide buffered communications with the specified remote 


host The GCP server supports high-level services with a peer 
GCP server, providing task-to-task communication, file trans¬ 
fer, and real-time voice. 

An evaluation kit that demonstrates the DLL costs $98; 
the Development Pack (including DLL, documentation, and 
sample application) costs $998; the Integrator's Toolkit costs 
$3,998 and includes everything in the Development Pack 
plus source code for the GCP++ DLL. Both the Development 
Pack and the Integrator's Toolkit allow you to distribute the 
GCP++ DLL with your application, royalty-free. For more infor¬ 
mation, contact GENISYS Comm, Inc., 314 S. Jay Street, 
Rome, NY 13440, (315) 339-5502; FAX (315) 339-5528. 


New Tools Automate Testing 

Dr. Taylor's Test automates repetitive testing for DOS 
programs; Dr. Taylor's Big Test uses a PC as an ASCII terminal 
to test UNIX, VMS, minicomputer, and mainframe software. 
The programs combine a memory-resident keystroke and 
screen recorder with an automated screen comparison tool. 
The software plays back recorded keystrokes at machine 
speed and can run overnight and unattended. Comparison 
screens and comprehensive reports document changes be¬ 
tween playback runs - planned or unexpected - and deter¬ 
mine the point at which a menu executes improperly or a 
command fails. 

The programs can operate either as TSRs or as control 
programs. The software requires about 13Kb when operating 


as a TSR and can be loaded into high memory. The TSR 
records and plays back test scripts, requiring no changes to 
the application. The programs can play back keystrokes in¬ 
teractively, at a fixed speed, or at machine speed, and can 
repeat the playback as many times as needed. 

Dr. Taylor's Test costs $199; Dr. Taylor's Big Test costs 
$499. Both include a 60-day money-back guarantee. For 
more information, contact Dr. Taylor's Software, Pinnacle 
Meadows, Richford, VT 05476, (800) 242-1114; FAX (800) 
242-6116. 


Alpha Logic Offers Timer Software Library 


VSTAT I is a virtual timers software library suitable for ex¬ 
ecution profiling, performance testing, interval measure¬ 
ment, precision delays and debugging. The library provides 
microsecond-resolution timing measurement capabilities, 
based on either Alpha Logic’s STATI timing board or in¬ 
dustrial counter/timer boards that use AMD's 9513 System 
Timing Controller 1C. 

VSTATI lets you create, destroy, start, stop, suspend, 
resume, and reset memory-based virtual timers. VSTAT! 
maintains timer statistics, including start/stop pass count, 
total time, and minimum, maximum, and average pass 


times. An event log captures timer and user-defined event 
time stamps in a capture buffer in memory. You can specify 
triggers that control what events get logged. Report func¬ 
tions allow you to then dump virtual timer statistics and 
event log capture buffers to screen, printer, or file. 

VSTATI includes a C software library with source code 
and reference manual for $149. For more information, con¬ 
tact Alpha Logic Technologies, Inc., 14636 N.E. 45th Street, 
Suite C-10, Bellevue, WA 98007, (206) 6 44-3094; FAX (206) 
883-2680. 
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Kansmen Updates ToolsKan Custom Controls 


The ToolsKan Development Toolkit is a package of six 
modules for Windows developers, compatible with Microsoft 
C, Borland C++, Turbo Pascal for Windows, and Quick C The 
3D Chart module generates two- and three-dimensional bar, 
area, and line charts. The Table module provides a spread¬ 
sheet-like user interface. The Status Bar module handles dis¬ 
playing a status bar of window information. The Toolbox 
module manages a three-dimensional array of buttons for 
access to program features. The Ribbon/Icon Bar module of¬ 
fers a ribbon such as Excel and Word for Windows use. The 
Field Validation module provides PIC-style validation for 
input fields. 

The new 3D Chart module now offers pie charts and sup¬ 
ports printing and the clipboard. The Table module now has 
column/row split windows, multiple column/row selections, 


and each column can be configured as bitmaps/radio but¬ 
tons and check boxes. The Status Bar now has automatic 
text scrolling for animation. The Toolbox can now create but¬ 
tons from bitmaps or text and also supports scrolling for 
large numbers of buttons. The Ribbon/Icon Bar now displays 
text in 3D form. The Field Validation module now can 
validate date/time and number fields. 

3D Chart costs $499 (the upgrade is free); the Table 
module costs $599 (upgrade is $200); the Status Bar module, 
Toolbox module, Ribbon/Icon Bar module, and Field Valida¬ 
tion module each cost $149 (upgrade costs $50 each). For 
more information, contact Kansmen Corporation, 2080-C1 
Walsh Avenue, Santa Clara, CA 95050, (408) 988-0634; 
FAX (408) 908-0639. 


Image SDK Plus Provides Enhanced Image Manipulation 


Black Ice Software, Inc, is now shipping the Image 
Software Development Kit (SDK) Plus. The toolkit provides 
functions for zooming, inverting, rotating and printing bit¬ 
maps, along with read/write routines for the clipboard (.CLP), 
metafile (.WMF), and bitmap (.BMP) file formats. This new ver¬ 
sion of the Image SDK adds anti-aliasing conversion and 
zooming of bi-level images, rotation of large images in 1-de¬ 


gree increments, image skewing, color space conversion, 
image enhancement filters, and selectable dithering. 

The Image SDK Plus costs $299.95 and includes complete 
documentation. For more information, contact Black Ice 
Software, Inc., Amherst Station, Route 122, Amherst, NH 
03031, (603) 673-1019; FAX (603) 672-4112. 


OPTLINK V3.0 Supports MSC V7.0 


OPTLINK v3.0 for Windows is a drop-in replacement for 
LINK and supports all compilers and assemblers that 
generate standard object files. The linker allows up to 64Kb 
each of libraries, symbols, segments, modules, and other link- 
specific information. The package supports CodeView v3.x 
and v4.x. Operating from DOS, OPTLINK v3.0 for Windows 
generates 16-bit .EXEs and .DLLs for both Windows and OS/2. 
Alternatively, OPTLINK v3.0 Segmented offers DOS and OS/2 
hosted linking for Windows and OS/2 executables. 

The new version of OPTLINK adds smart-linking technol¬ 
ogy and P-code support for Microsoft's C/C++ v7.0. Smart link¬ 


ing lets you eliminate all unreferenced functions in order to 
save space in the resulting executable. In addition to 
eliminating the need to run the Windows resource compiler, 
OPTLINK provides “/exepack” functionality towards building a 
Windows executable. 

OPTLINK V3.0 for Windows costs $350 and OPTLINK v3.0 
Segmented costs $499. For more information, contact SLR 

Systems, Inc., 1622 N. Main Street, Butler, PA 16001, (412) 
282-0864; FAX (412) 282-7965. 


Phar Lap Updates 2861 DOS-Extender 

Phar Lap Software, Inc, has released a new version of 
their 2861 DOS-Extender. 2861 DOS-Extender is a 16-bit ex¬ 
tender that allows programs to access up to 16Mb of 
memory on any DOS-based 80286, 80386, or 80486 PC In ad¬ 
dition to Microsoft and Borland C/C++ compatibility, the ex¬ 
tender is also compatible with Microsoft Fortran. 

Version 2.5 allows developers to build multi-megabyte 
DOS applications using the latest compiler releases from 
Microsoft and Borland: Microsoft C/C++ v7.0 and Borland C++ 
v3.1. The new version features faster floating point for 
Microsoft C/C++ users and huge memory model support for 


Borland C++ users. Version 2.5 also supports Borland's Turbo 
Debugger as well as all of the Microsoft C/C++ v7.0 protected- 
mode tools, including CodeView for Windows. 

The 2861 DOS-Extender Software Development Kit (SDK) 
v2.5 costs $495. Upgrading from the 2861 DOS-Extender SDK 
costs $75; upgrading from the 2861 DOS-Extender Standard 
Run-Time Kit (RTK) costs $150. For more information, contact 
Phar Lap Software, Inc., 60 Aberdeen Avenue, Cambridge, 
MA 02138, (617) 661-1510; FAX (617) 876-2972. 


Pryor and Pryor Offers Communications Libraries 


Pryor and Pryor Inc. has released three new communica¬ 
tions products for C or assembly language programmers. 

The SPI library is a communications library module for 
serial ports that can share interrupt request lines. It can co¬ 
exist with a mouse on either IRQ4 or IRQ3 at data rates up to 
4,800 baud, on any XT through 80486 machine. When not 
sharing an IRQ, it will run at rates up to 115,200 baud. 

The FCL library is a file compression library that can be 
used in dynamically compressing file transfer programs as 
well as in simple disk file compression programs. 


The SDA serial data analyzer program converts any PC 
into a tool for monitoring and displaying RS232 data flow. 
The user can select display modes, capture and store data in 
real time, play back previously captured data, and print the 
displayed information. 

The SPI library costs $49; the FCL library costs $49; the 
SDA serial data analyzer costs $ 159, or $229 with cable. For 
more information, contact Pryor and Pryor, Inc, 602 - 1230 
Comox Street, Vancouver, B.C, Canada, telephone/FAX 
(604) 669-2609. 
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New Book Tackles OLE and DDE 

Jeffrey D. Clark has written a new 450-page book called 
Windows Programmer's Guide to OLE/DDE. The book and ac¬ 
companying disk help programmers develop Windows ap¬ 
plications that support Object Linking and Embedding and 
Dynamic Data Exchange. Example applications include server 
applications, client applications, and monitor applications to 
use with DDE. The book also shows how to develop an OLE 

Borland Ships Brief v3.1 

Borland International Inc is now shipping BRIEF v3.1 for 
DOS and OS/2. Formerly sold by Solution Systems as two 
separate products, BRIEF will now include both DOS and OS/2 
versions in one package. 

BRIEF is a programmer’s editor that features a macro lan¬ 
guage, smart compilation from within the editor, multiple 
language support, smart indenting, statement completion, 


object handler. The companion disk includes all the book’s 
program listings. 

The recommended US price for the book (including the 
disk) is $34.95. ISBN: 0-672-30226-8. For more information, 
contact Sams, 11711N. College Avenue, Suite 140, Carmel, 
IN 46032, (800) 428-5331. 


and window support. New features include mouse support, 
the ability to take advantage of EMS memory, redo 
capability, and dialog box support 

BRIEF for DOS and OS/2 costs $249.95. For more informa¬ 
tion, contact Borland International, Inc., 1800 Green Hills 
Road, P.O. Box 660001, Scotts Valley, CA 95067-0001, 
(408) 439-4833. 


MicroTAP Adds New COM Monitoring Features 


Paladin Software, Inc has released a new version of 
MicroTAP (formerly DataScope), a communications debug¬ 
ging, data capture, and analysis tool. MicroTAP is a serial line 
monitor that includes context-sensitive hypertext Hyper¬ 
setup, user-alterable multitasking window displays, and oscil 
loscope-like signal event tracing. All data and signal events 
are timestamped to the microsecond. Version 2.1 adds CUA- 
compliant file management signal pattern triggering (includ¬ 


ing “don’t care" signals), and expanded data stream trigger¬ 
ing (logical AND and OR functions, user selectable source 
streams, and wildcard bytes in binary or alphanumeric trig¬ 
ger strings). 

MicroTAP v2.1 costs $299, which includes cable, connec¬ 
tors, and manual. For more information, contact Paladin 
Software, Inc, 3945 Kenosha Avenue, San Diego, CA 
92117, (619) 490-0368; FAX (619) 490-0177. 


Pen InputMaster Brings Pen Input Control to Visual Basic 


Pen InputMaster is a custom control for Visual Basic that 
allows developers to create pen applications by adding the 
control to Visual Basic Pen InputMaster looks like an entry 
field on a paper form, providing a text label and adjacent 
input line, but it provides four ways to input data with the 
pen. The user can write directly on to the input line, tap the 
text label to display a drop-down list to select from, or use 
gesturing to bring up either a larger edit box or an on-screen 
keyboard. 


Pen InputMaster offers programmers configurability, with 
fully customizable fonts and complete TrueType support. 

The control also provides automatic sizing, spacing, and align¬ 
ment, allowing programmers to build forms with multiple 
input areas that all neatly line up. 

Pen InputMaster costs $99 and is royalty-free. For more 
information, contact StylusTech, Inc, Suite 300, Building 
600, One Kendall Square, Cambridge, MA 02139, (617) 277- 
7007; FAX (617) 277-8907. 


HSWIN Brings HI-SCREEN Pro II to Windows 


HSWIN is a Windows 3.x add-on module for HI-SCREEN 
Pro II, a user interface system compatible with all program¬ 
ming languages. Combined with HI-SCREEN Pro II, HSWIN lets 
developers create user interfaces for Windows programs. It 
also enables them to quickly move any DOS application to 
Windows, with virtually no source code modifications. 

DOS applications developed with HI-SCREEN Pro II can be 
easily ported to Windows; all DOS interface objects such as 
screens, menus, and icons are automatically converted to 


Windows 3.x resources using the built-in library generator. 
Existing code can then be recompiled with a Windows-com¬ 
patible compiler, creating a true Windows program. HSWIN 
handles all events (mouse clicks, keyboard presses, etc) 
automatically. 

The HSWIN DLL costs $250 and is royalty-free. For more 
information, contact Softway, Inc., China Basin Landing, 

185 Berry Street, Suite 5411, San Francisco, CA 94107, 
(415) 896-0708; FAX (415) 8 96-0709. 


Quarterdeck Adds DPMI Support to QEMM-386 


Quarterdeck has released a DOS Protected Mode Interface 
(DPMI) host, a companion product to QEMM-386, its memory 
management program. The Quarterdeck DPMI host is com¬ 
patible with Microsoft C/C++ v7.0, Borland C++ v3.0, and Intel's 
Code Builder Kit v 1.1. The host supports virtual memory, giving 
programs access to more memory than is physically present 
The Quarterdeck DPMI host is a full implementation of 
version 0.9 of the DPMI specification, including DOS exten¬ 
sions. The DPMI host supports running multiple DPMI 
programs inside Quarterdeck's DESQview products. 


The Quarterdeck DPMI host is available free to registered 
users via the company's user bulletin board system: (310) 
314-3227. Users who require packaging and hard copy 
documentation can order the DPMI host directly from 
Quarterdeck for $30: (800) 354-3222 (no charge to Quarter¬ 
deck Passport Support subscribers). For more information, 
contact Quarterdeck Office Systems, 150 Pico Boulevard, 
Santa Monica, CA 90405, (310) 392-9851; FAX (310) 399- 
3802. 
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Reader-Contributed Tricks and Hacks 
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Tech Tips 



Edited by 
Leor Zolman 


Please send us your best 
tricks and hacks — those 
c/ever pieces of code to 
make things work the 
way they should! You’ll 
receive at least $50 for 
each tip that we print. 
Send your submissions to.- 
Tech Tips 
Leor Zolman 
74 Marblehead Street 
North Reading, MA 01864 
leor@bdsoft.com. 


This last issue of the third volume of Windows/DOS Developer's Journal marks 
the twentieth installment of this Tech Tips column. Back when Tips began, I 
wasn't sure whether to expect a flood of reader contributions or a trickle; after the 
first year (during which Tips were arriving at the rate of one column’s worth every 
two months or so), I've consistently had just about the the right number of good 
Tips on hand to fill the space Martha has had available for me each month. While 
I'm grateful there have been enough Tips to generate a regular column, I’d rather 
see a massive Tips surplus. Perhaps by demystifying some of this column’s work¬ 
ings, I can entice you to write up that Tip you've been thinking of submitting. 

The sidebar says we pay at least $50 for each Tip printed. If you interpret this 
the way I would if I were reading it in some other magazine, you might think we 
just pay a flat $50 per tip. That is not the case; for each Tip, I plug variables such 
as length, clarity, code quality, and amount of rework necessary into a purely 
objective evaluation algorithm (NOTH) - in other words, I capriciously decide 
how much we're paying for that Tip based on what I think it's worth. For short 
ones with little or no companion code I usually allot $50, but most Tip contributors 
actually receive between $75 and $125 for their effort. You may see the same 
names pop up time after time beside those little light bulbs; these are the folks 
who know a good thing when they stumble upon it! Help divide the wealth; send 
in a tip today! (Well, OK, take a few days first to polish the documentation and get 
out the bugs.) 


Leor Zolman wrote 60S C, the first C compiler targeted exclusively for personal com¬ 
puters. He is a columnist for both The C Users Journal and Windows/DOS Developer's 
Journal. Leor's first book. Illustrated C, was published by R&D in January 1992. He may 
be contacted at 74 Marblehead Street, North Reading, MA, 01864, or on the net as 
leor@bdsoflcom. 
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Listing 1 switch, c 


/* SWITCH.C Donna Campanella 

Program to switch between Monochrome mode and EGA/VGA Color Mode 
for computers with both a color and monochrome video adapter and 
dual monitors. Detects the currently active display and switches 
to the alternate one. Does not clear the screen when switching 
to color mode as DOS's MODE.COM does. */ 


linclude <dos.h> 

Idefine MONO_MODE 0x30 

#define MONO 7 

Idefine COLOR 3 

Idefine VIDEO 0x10 

Idefine SET_VIDE0_M0DE 0x00 

Idefine SET_CURSOR 0x02 

Idefine CURS0R_C0L 0 

Idefine SCREEN_ROW 0x18 

Idefine VIDEO PAGE 0 


Idefine CURRENT_MODE_ADDR 0x410 

/* CURRENT_MODE_ADDR: The two-byte word at 410h as defined in 
Norton's Programmer's Guide to the IBM PC: (pg 52-53) 

Word that holds the equipment list that is reported 
by equipment-list service interrupt 17 (hex 11) (pg 219) 

Initial video mode: 76543210 
x x 

where: 10 ==> 80 column color 

11 **> 80 column monochrome 

Set/clear bit to switch modes. */ 

void main() 

{ 

union REGS regs; 
int new_mode; 

unsigned char video_mode, far *vid_mode_ptr; 

/* Get current active display */ 
vid_mode_ptr - (int far *) CURRENT_MODE_ADDR; 
video_mode * *(vid_mode_ptr); 

/* Test current mode and switch to alternate mode */ 
if ((videojnode & M0N0_M0DE) == MONO_MODE) 

( 

/* clear bit to set color mode */ 
videojnode &= OxEF; 
new_mode = COLOR; 

) 

else 

( 

/* set bit to set monochrome mode */ 
videojnode |= 0x10; 
newjnode ■ MONO; 

) 


/* Enable the display by updating the "equipment list" */ 
*vid_mode_ptr = videojnode; 

/* Switch mode, setting high bit in AL (OR mode with *1 
/* hex 80) to avoid clearing the EGA/VGA screen. */ 

regs.h.al » (char) (newjnode | 0x80); 
regs.h.ah = SET_VIDE0_M0DE; 
int86(VIDE0, &regs, &regs); 

/* Set cursor to bottom of screen */ 
regs.h.ah = SET_CURSOR; 
regs.h.dh = SCREEN_ROW; 
regs.h.bh = VIDEO_PAGE; 
regs.h.dl = CURS0R_C0L; 
int86(VIDE0, &regs, &regs); 

} 

/* End of File */ 


With rare exceptions, I make it my 
policy to verify every Tip submitted 
before I publish it. If you send your 
submissions in via paper mail, please 
also put your text and program code 
on a floppy disk so I don't have to 
retype it. Any DOS-compatible format 
is fine. While I might type something in 
if it is short and seems interesting 
enough, please don’t count on it. 

Tips are also welcome via Inter¬ 
net/Usenet e-mail. Note that you can 
now send to an Internet address 
directly from CompuServe, and per¬ 
haps other conferencing systems. See 
the sidebar for my Internet e-mail ad¬ 
dress. 

That's it for this month’s ad- 
ministrivia. Happy holidays, everyone, 
and special thanks to all of you who've 
contributed Tips and feedback to this 
column over the years. It has been ex¬ 
tremely enjoyable for me so far, and I 
expect the party to continue for at 
least as many years to come. -Iz 



Dual Displays — Switching 
between Color 
and Monochrome 


Donna Campanella 
508 Natalie Lane 
Norristown, PA 19401 


I would like to share the enclosed 
programs as a replacement for DOS's 
mode.com to switch between a 
monochrome and color display. 

I initially purchased my home com¬ 
puter system with a Super VGA display. 
I later installed a monochrome card and 
monitor, because in addition to using 
the second monitor for debugging, I 
thought it would also be helpful to be 
able to display pieces of text or direc¬ 
tory listings, etc. on the alternate 
monitor for reference. Nowadays, most 
applications are being developed for 
graphical operating and systems en¬ 
vironments, and I would imagine that a 
dual monitor setup to aide with debug¬ 
ging is very popular. 

Traditionally, the methods I have 
seen use DOS’s mode.com to switch be¬ 
tween monochrome and color by ex¬ 
ecuting mode mono and mode co80. Al¬ 
though this works adequately, when 
you switch to a mode, the screen that 
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Listing 2 switch.pas 

{ SWITCH.PAS Donna Campanella 

var 

Procedure to switch between Monochrome mode and EGA/VGA 

new mode : integer; 

Color Mode for computers with both a color and monochrome video adapt- 

video mode : word; 

er and dual monitors. Does not clear the screen when switching to 

begin 

color mode as DOS's MODE.COM does. Cursor Is positioned at the row and 

video mode := CURRENT MODE ADDR; 

column on the video page specified. Valid modes to switch to are the 

If switch to = MONO MODE then 

80x25 text monochrome or color modes Indicated by the parameter 

begin 

MONO MODE or COLOR MODE. ) 

{ set bit to switch to mono mode } 


video mode := video mode or $10; 

unit switch; 

new mode := MONO; 

Interface 

end 

uses dos; 

else 

type 

begin 

mode = (MONO MODE, COLOR MODE); 

{ clear bit to switch to color mode } 

const 

video mode := video mode and $EF; 

MONO = 7; 

new mode := COLOR; 

COLOR = 3; 

end; 

VIDEO = $10; 


SET VIDEO MODE = 0; 

{ Enable the display by updating the "equipment list" } 

SET CURSOR = 2; 

CURRENT MODE ADDR := video mode; 

var 


regs : registers; 

( Switch mode, setting high bit in AL (OR mode with ) 

CURRENT MODE ADDR: word absolute $0000:10410; 

{ hex 80) to avoid clearing the EGA/VGA screen. } 

( CURRENT MODE ADDR: The two-byte word at 410h as defined in 

new mode := new mode or $80; 

Norton's Programmer's Guide to the IBM PC: (pg 52-53) 

regs.al := new mode; 

Word that holds the equipment list that is reported 

regs.ah := SET VIDEO MODE; 

by equipment-list service interrupt 17 (hex 11) (pg 219) 

intr(VIDEO.regs) ; 

Initial video mode: 76543210 


X X 

( Set cursor postion } 

where: 10 ==> 80 column color 

regs.ah := SET CURSOR; 

11 ==> 80 column monochrome 

regs.dh := cursor row; 

Set/clear bit to switch modes. ) 

regs.bh := video page; 


regs.dl := cursor col; 

procedure switch mode(sw1tch to : mode; cursor row, cursor col, 

intr(VIDEO.regs); 

video page : Integer); 


implementation 

end; 


end. 

procedure switch mode(switch to : mode; cursor row, cursor col. 

( End of File ) 

video_page : Integer); 



BUILD A MINI-DATABASE 
SYSTEM WITH . . . 



Illustrated 

* O 

Leor Zolman 

CUJ columnist and 
author of BDS C 


Discover the WHY and HOW of application design 
and development in C. Explore the construction of 
several different applications from start to finish. 
Chapter after chapter you’ll develop your skills 
through in-depth tutorial and detailed code. 
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Listing 3 testswch.pas 


{ TESTSWCH.PAS Donna Campanella 

Program to demonstrate the call to the procedure SWITCH_MODE in the 
SWITCH.TPU unit. Two lines are written to the color display without 
clearing the display, and one line is written to the monochrome display. } 

program testswch; 
uses switch; 

begin 

switch_mode(MONO_MODE,3,3,0); 

writeln(’Printed on Monochrome screen row 3 column 3...'); 
switchmode(COLOR_MODE,20,5,0); 

writeln('Printed on Color screen row 20 column 5...'); 
switch_mode(C0L0R_M0DE,2,22,0); 

writeln('Printed on Color screen row 2 column 22...'); 
end. 

( End of File ) 


you are switching TO is cleared (the screen is not cleared on 
the monitor you are switching FROM). I thought it would be 
more beneficial to be able to append output to any previously 
displayed output. After some investigation, I found information 
indicating that when the mode is changed using I NT lOh 
Function OOh, the screen is cleared. For EGA and above, PCjr’s, 
and PC Convertibles only, you can avoid clearing the screen by 
calling the function with the high bit in AL set. So, based on 
that information, I developed switch.c (Listing 1) as a replace¬ 
ment for mode.com. switch leaves the color screen intact — 
the cursor is placed at the bottom of the screen and any 


further output can be “appended” to 
the previous. When switching to the 
monochrome display, however, the 
screen is still cleared. 

switch is also more intelligent than 
mode in that it checks the currently ac¬ 
tive display (as indicated by the 2-byte 
word at hex 410) and switches to the 
alternate display without having to 
specify co80 or mono. 

I have also included a Turbo Pascal 
version of switch (Listing 2) designed to 
be compiled into a unit. The procedure 
switch_mode can be called from a pro¬ 
gram to write.to the appropriate display 
and cursor position desired (without 
clearing the color screen). The Pascal 
program testswch (Listing 3) 
demonstrates calling the procedure to write two lines of text 
to the color display and one line to the monochrome display. 

Because of the popularity of graphical operating environ¬ 
ments and systems, fewer and fewer computer users are 
booting native DOS. The particulars of Windows’ and OS/2's 
video wizardry are bound to change with newer versions of 
video drivers. I don’t know about Windows, but switch also 
works in OS/2 2.0 DOS Fullscreen sessions. OS/2 seems to 
handle OS/2 and DOS Fullscreen sessions differently. Unlike na¬ 
tive DOS, where only the screen you are switching TO is 
cleared, executing MODE under OS/2 DOS Fullscreen sessions 


—* 

TX Text-Control for MS Windows 

▼ 



Do you need WYSIWYG Text Processing in 
your Windows Application? No Problem! 




Paragraph 


Font 

alignment: 


attributes: 

left 




types: 

italic 

centered 


underline 

right 

right 

strikeout 

justified 

centered 

:r^ P t 


decimal 

- for all printer fonts 1 

i 


Just use the TX Text-Control DLL to integrate features 
like multiple fonts, paragraph formatting, zooming or 
tabs. Even pictures can be included with an additional 
tool, the 1C Image-Control. 

Get your free demo today! 

Call 203-521-0881 (USA or Canada) 

The Aristos Company, 181 Loomis Dr. Suite 146 
West Hartford, CT 06107, Phone 203-521-0881 
Fax 203-561-2045, CompuServe 73020,2101 

Elsewhere contact 
DBS GmbH, FahrenheitstraBe 1 
2800 Bremen 33, Germany 
Phone +49 421 /22 08-162 
Fax +49 421 / 22 08-273 
CompuServe: 100013,115 

Windows is a trademark of Microsoft Corporation 
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windows/DOS Code Listings 
Available via UUCP! 

The listings for all code in each issue of Win¬ 
dows/DOS Developer’s Journal are now being archived 
in machine-readable form by UUNET Technologies, Inc. 
Each archive file has a pathname of the form 

uunet!~/published/windowsdos/19YY/monYY.zi p 

where mon is the first three letters of the month (jan, 
feb, etc.) and YY is the last two digits of the year (e.g., 
92). To uncompress the archives, use unzip filename. 
See the file called filename.txt, included in each ar¬ 
chive, for an explanation of the archive's contents. This 
directory is also accessible via anonymous FTP from 
ftp.uu.net. 

You may download these archive files via uucp 
even if you do not have a UUNET account: have your 
uucp program call 1-900-GOT-SRCS and use the login 
name uucp, no password. Callers will be charged a 
nominal fee for connect time (currently 50 cents per 
minute). The modems are mostly Telebit T3000’s, 
which support most of the faster communication 
protocols. 

Code for each issue is also available on diskette 
from R&D Publications at $5.00 per disk (call 913-841- 
1631 for information). / \ 

RD 
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Listing 4 winbox.asm 


WINBOX.EXE written by Guy Eddon, 1992 

MASM 5.1: 

MASM WINBOX.ASM; 


LINK WINBOX; 

MASM 6.0: 

ML /Zm WINBOX.ASM 

TASM: 

tasm winbox 


tlink winbox 


assume cs:_TEXT,ds:_DATA,ss:STACK 

_TEXT segment word public 'CODE' 

Print proc far 

mov ax,_DATA 

mov ds,ax 

mov ah,09h 

mov dx.bx 

int 21h ; DOS - Display string, 

retf 

Print endp 
Getch proc far 

mov ax,0700h 

int 21h ; DOS - Get key without echo, 

retf 

Getch endp 

Winbox proc far 

Start: 

mov ax,1600h 

int 2Fh ; Win - Is enhanced mode running? 

jc EnhancedModeNotRunning 

cmp al,0 

je EnhancedModeNotRunning 

cmp al,80h 

je EnhancedModeNotRunning 

jmp EnhancedModelsRunning 


EnhancedModeNotRunning: 

mov bx,offset m2 

call Print 

jmp Exiting 

EnhancedModelsRunning: 


mov bx,offset ml 

call Print 

mov bx,offset m3 

call Print 

mov bx,offset m4 

call Print 

call Getch 

mov bx,0015h ; DOSMGR VxD. 

mov ax,1684h 

int 2Fh ; Win - Get API entry point in ES:DI. 

mov ax.seg CriticalSection 

push ax 

mov ax,offset CriticalSection 

push ax 
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volumes 

• capsule summaries 
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to volumes 250-300 of 
the CUG public domain 
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Call 

TODAY! 


913 - 841-1631 



clears BOTH the monochrome and color 
screens. However, switch works as it 
does under native DOS, leaving the 
color screen intact when switching to it. 
in OS/2 DOS sessions, pressing CTRL+ESC 
temporarily blanks the monochrome 
screen — the screen is restored when 
you return to the DOS session. In OS/2 
Fullscreen sessions, executing MODE 


clears both the monochrome and color 
screens —in this case, pressing CTRL+ESC 
brings up the Desktop on the VGA 
screen, while retaining any text on the 
monochrome display. 

I hope that others with a dual 
monitor system will find these 
programs helpful. 


Listing 4 

continued 

push 

es 

push 

di 

mov 

ax.OOOlh 

retf 

; Returns to ES:DI, then to Critical. 


CriticalSection: 


mov ax,1681h 

int 2Fh ; Win 

mov bx,offset m5 

call Print 

mov bx,offset m9 

call Print 

mov bx,offset m6 

call Print 

mov bx,offset m4 

call Print 

call Getch 

mov ax,1682h 

int 2Fh ; Win 

mov bx,offset m7 

call Print 

mov bx,offset m8 

call Print 

Exiting: 

mov ax,4C00h 

int 21h ; DOS - Exit with return code 0. 

Winbox endp 

_TEXT ends 

_DATA segment word public 'DATA' 

ml db ODh.OAh,'Windows is running in enhanced mode.', 0Ah,0Dh,'$' 
m2 db ODh.OAh,'Windows is not running in enhanced mode.', 0Ah,0Dh,'$' 
m3 db 'WINBOX will now switch to full screen mode.', 0Ah,0Dh,'$' 
m4 db 'Press any key to continue . . .', OAh,ODh,OAh,ODh,'$' 
m5 db 'WINBOX is now running full screen.', 0Ah,0Dh,'$' 

m6 db 'Multitasking, Alt-Enter, and Alt-Tab are now unavailable.', 0Ah,0Dh,'$' 
m7 db 'WINBOX has exited the critical section.', 0Ah,0Dh,'$' 
m8 db 'Windows is now operational.', 0Ah,0Dh,'$' 
m9 db 'WINBOX has entered a critical section.', 0Ah,0Dh,'$' 

_DATA ends 

STACK segment para stack 'STACK' 

db 128 dup (0) 

STACK ends 

end Start 
; End of File 


- Begin critical section. 


- End critical section. 
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WINBOX - A Protected 
Full-Screen Mode for DOS 
Applications under Windows 

Guy Eddon 
Donovan Data Systems 
115 West 18th Street 
New York City, NY 10011-4113 
CIS 71172,1014 


Version 5.0 of MS-DOS includes a 
program named UNDELETE, written by 
Central Point Software. When run, UN¬ 
DELETE switches to full-screen mode 
from a windowed DOS box and then 
locks the system before attempting to 
recover any files. This ensures that no 
other programs interfere with UNDELETE 
during its crucial operations. Many 
other programs could benefit from 


Listing 5 activate.c 


/* 

* ACTIVATE.C (C) Copyright 1992 Aki Korhonen 

* 

* How to kill "Insert diskette for drive X:“ 

* Turbo C 2.0 

* 

* main() function is a test driver for the 

* activate_drive() function. On a single-drive 

* system, create a file on the floppy drive named 

* "TEST.FIL". With the disk in the drive, compile and 

* run this program with ACTIVATE defined to 0 (plain way) 

* and then to 1 (to use the activate_drive() function). 


fdefine ACTIVATE 1 /* make this 0 to test "plain" way */ 

finclude <stdio.h> 
finclude <stdlib.h> 

finclude <dos.h> /* for intr() */ 

linclude <dir.h> /* for fnsplit() */ 

#include <conio.h> /* for toupper() */ 

linclude <io.h> /* for open() */ 

linclude <fcntl.h> /* for 0_RDONLY */ 

linclude <ctype.h> 

void activate_drive(char ‘pathname); 

void main() 

{ 

lif ACTIVATE 

/* Want to open a file? First make sure the drive is ok. */ 
activate_drive("A:TEST.FIL"); 
lendif 


if (close(open("A:TEST.FIL\ 0_RD0NLY))) 
exit(puts("Can't open A:TEST.FIL")); 

lif ACTIVATE 

/* And again. Look ma! No stinkeen dos messages! */ 
activate_drive(“B:TEST.FIL"); 
lendif 

if (close(open("B:TEST.FIL", 0_RD0NLY))) 
exit(puts(“Can't open B:TEST.FIL")); 

) 

void activate_drive(char ‘pathname) 

I 

struct REGPACK rp; 

char si[4] , s2[70], s3[10], s4[6]; 


fnsplit(pathname, sl,s2,s3,s4); 

if (si[0]) { 
rp.r_ax=0x440F; 

rp.r_bx=toupper(sl[0])- 1 A 1 +1; 

intr(0x21, &rp); 

} 

1 

/* End of File */ 


/* Split path into components */ 

/* drive named? if so, verify */ 
/* AX=440FH == Set Logical 

Drive Hap, since DOS 3.2 */ 

/* BL=Drive I we want 

to use (A=l, B=2 ...) */ 

/* Make the DOS call */ 


Universal 
Printer 
Driver 

Would Text and Graphic 
Printer support for over 
750 Printers (including 
PostScript) give you a 
competitive edge? 

By including SLATE, you can print 
both Text and Graphics on over 750 
printers (including PostScript, 
LaserJet III and the new Epson 
scalable font printers). 
Immediately! Painlessly! 

You can use SLATE in your product 
with no royalties. 

SLATE gets you out of the printer 
support business. Forever! 

Make your product more functional 
and competitive by using SLATE'S 
advanced text features: 

• Support multiple printers on the same 

system. 

• Output to parallel printers, serial printers, 

DOS files/devices, DOS print spooler, 
and Novell network printers. 

• Include end user's soft fonts. 

• Support cartridge fonts. 

• Support proportional fonts 

• Support scalable font printers. 

• Set exact print positions. 

• Color printing 

• Kerning, leading, overstrike, underlining, 

and strike through. 

• Automatic character set conversion. 

SLATE with Graphics adds advanced 
graphic printing features: 

■ Print images from the screen, PCX or TIFF 
files, or custom image systems. 

• Scale and Rotate the printed image. 

• Print grey scale and color images. 

• Intermix text and graphics. 

SLATE is a set of C or Basic libraries 
with over 170 text printing functions, 

a Database of over 750 printers, 
and End User configuration and 
testing programs. 

SLATE with Graphics adds over 60 
graphic printing functions. 

Call now for a complete developer's 
information kit. Order SLATE for 
only $299 or SLATE with Graphics 
for $448 with our risk free, 30 day 
return policy. 

We accept Visa, MasterCard, COD's or PO's 
from qualified companies. Source code, 
maintenance, and site licenses are available. 

800-346-3938 

The PO Box 26195 

Qvmmptm Columbus, OH 43226 
symmetry 614 .4 31 . 2667 

Uroup FAX 614-431-5734 
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this technology, including, for example, the Norton disk 
utilities, DOS programs which switch to graphic modes, 
programs which do mainframe communication, and any other 
program which performs tasks which cannot be interrupted. I 
wrote WINBOX to demonstrate how to: 

1. Switch windowed DOS boxes to full screen mode. 

2. Lock the system so that DOS programs have full control 
over their environment 

Conceivably, these options could be specified in a PIF (pro¬ 
gram information file). However, a power user could modify 
these settings. By using the method shown in the WINBOX 
program (Listing 4), you can control the windowed DOS en¬ 
vironment your program runs in. 

WINBOX does not require that you install any special VxDS. 
Instead it uses the services of the DOSMGR virtual device 
which is part of WIN386. There is an example that comes with 
the MS-Windows 3.1 DDK which shows how to find out if your 


DOS program is being run full-screen or in a window. However, 
it requires that you install a special VxD, and only allows your 
program to query the status, not to set it 

More on Single-Floppy DOS 
Message Suppression 


Aki Korhonen 
125 Searidge Ct #D 
Aptos, CA 95003 

In the July 1992 issue you had a Tech Tip with the purpose 
of solving the DOS message “Insert diskette for drive B: and 
strike any key when ready.” Unfortunately, the program that 
was supposed to remove this message has severe flaws in it. 
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The Ah of Visual Basic Programming ™ 

This amazing new book by J. D. Evans, Jr. unlocks 
the secrets of Windows and Visual Basic 
application design and programming. It explains 
Windows design from a unique and easy to 
understand perspective. Smart Objects, Hybrid 
Objects, Control Coupling, Events, Focus, Event 
Triggering, Visibility, Form and Module Code 
Placement, DLL Parameter Passing, Variable 
Scope, Strings, and Structures are described and 
explained. Enlightening allegories and annecdotes 
make this one of the most unusual and informative 
Windows books ever written. This book is the 
Rosetta stone for Windows and Visual Basic! 


Book: $29.95 Companion Disk: $9.95 
ETN Corporation 

RD4 Box 659 Montoursville, PA 17754-9433 
(717) 435-2202 (Sales) (717) 435-2802 (FAX) 
AMEX/MC/VISA/Check/MO/PO/COD 
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NETWORK 

CONTROL 

LIBRARIES 

NETBIOS ROUTINES allows ac¬ 
cess to low-level network func¬ 
tions. Name, session, and 
datagram routines. Wait and no¬ 
wait options. $99 

NETBIOS DLL for Windows $199 

NETWORK MASTER provides 
access to Netware internal func¬ 
tions. Complete network control 
from your compiled programs! $99 

Starlight Software 

P.O. Box 1090 
Wheeling, IL 60090 

(708) 394-0622 _ 
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SEdLEVEL 


COM1: - COM4: 
WITH WINDOWS! 

• 1. 2, OR 4 PORT RS-232 BOARDS 

• RS-232 AND RS-422 VERSIONS 

• WINDOWS UTILITY SOFTWARE 
PfO VIDEO 

. XT AND AT INTERRUPT JUMPERS 

• OTHER PRODUCTS INCLUDING 
LAPTOP ADD-ONS 

■ DELIVERY FROM STOCK 
> MADE I: 


SEALEVEL SYSTEMS INC. O 
PO BOX 830 
LIBERTY, SC 29657 

( 803 ) 843-4343 


*1 
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NetBIOS MADE EASY! 

for Win dows 3.x and DOS 

□ Shared DLL resources 
supports multiple 
applications and instances. 

□ Full post processing support 
& notification via messages 
(wait, no-wait, and polled). 

□ Complete NCB and attached 
data buffer functions simplify 
memory management. 

□ Single source for Windows & 
DOS with WINDOWS.TXT. 

□ Windows setup program and 
complete documentation. 

□ No royalties, full source and 
demo programs $155.00! 

SIGMA SOFTWARE RESEARCH 
702 Windridge Dr 
Atlanta, GA 30350 
TEL (404) 992-0536 

Also available at the Programmers Shop! 
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^ WindowsCreator ^ 

anniversary price ^$85 

■'"create WINDOWS interactively 
'"no need to write any code 
'"You PAINT the application,not write!!! 
'"object-oriented programming using 
standard C-language 
'"Generated C-code or Smalltalk code 
in seconds! I 

'" Dialog, window, menu, cursor 

icon, color, brush and attrib. 

editors included. 

'"interactive functionality linking 
'"application code is separated from 
interface code. Few code lines connect 
application to WINDOWS 3.x interface 

AdamSoft 

13 rue de Crecy,L-1364 Luxembourg 
Fax:+352-494768. VISA accepted 
p&p Europe $10,elsewhere $20 
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Create High 
Performance 
Network 
Applications 
FASTI 

60 Day 
Money Back 
Guarantee! 










































Over 100 routines 
give you complete 
control of axes, 
scaling, windows, 
and more 

Sutrasoft 

10506 Pwmlan Dr. 
Sugar Land, TX 77478 

Info: (713) 491-2088 

FAX: (713) 240-6883 


HORNER PLOT 
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NETWORK 

LIBRARY 



The most comprehensive library for Net¬ 
Ware available anywhere! Over 400 func¬ 
tions providing services and statistics for 
all versions of NetWare including: 


accounting 

bindery 

connection 

console 

directory 

file 

file server 
IPX comm. 


locking 
message 
printing 
queue mgt. 
security 
semaphore 
trans. tracking 
workstation 


Over 125 sample programs including 
source code for most NetWare command 
line utilities (such as capture, nprint, login 
and logout) and reports. Over 550 pages of 
documentation. 8i 88 -s St Rt 48 

Maineville, OH 45039 
Toll Free: 800-669-0842 
FAX:513-677-3123 
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FAST TEXT SEARCH 
for C / Windows 


The fastest, easiest and most versatile way to 
add full text search capabilities to your C and 
Windows applications, FAST TEXT SEARCH 
for C is a function library enabling rapid 
searches of both structured and unstructured 
textual data with low overhead/memory 
requirements, low cost and high efficiency. 
Great with CodeBase, SoftC, AccSys, etc. 
No Risk 30 day Money Back Guarantee 

Order - (800) 334-8099 
Only $189.00 

Windows/DOS Developer’s Journal Special includes 
UltraSearch & Free 2 Day Shipping 

DOS (Microsoft, Borland) and OS/2 libraries 
& Windows DLL, royalty free integrator license, 
complete printed documentation, sample 


prog 1 

VISA/MasterCard/COD/Qualified PO s accepted. 


rams & free technical suj 


jpport. 
Os acc 




Index Applications Incorporated 

H 8546 Broadway, Suite 208 
San Antonio, TX 78217 USA 
512 / 822-4818; fax: 512 / 828-5074 
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ADVANCED 

DATABASE ENGINE DLL 

Add advanced database management capabilities to 
your programs with simple function calls. Andsor 
Database Engine for Windows is a DLL you can use 
from C, Visual Basic, and many other languages 
and front-ends. 

• Functions range from simple ISAM file 
operations to full database management. 

• Makes your Windows programs smaller and 
simpler by replacing large sections of code with 
short procedures you create, test, and store in the 
database itself. 

• Ideal for business applications. 

1-800-766-1141 

$ 149 120-day money-back guarantee 

Andsor Research Inc. 

390 Bay St., Suite 2000 
Toronto, Ontario, Canada M5H 2Y2 

(416)245-8073 Fax (416)240-8473 


Developer's Toolkit 

ZvINDEX 


Fastest, most 
powerful text retrieval 
technology available 

• Search 100 MB in < 3 seconds 

• Up to 50 million documents, 2 GB total 
text per index 

• Powerful searches: word, phrase, proximity, 
Boolean, wildcards, and more 

• Supports MS Word, WordPerfect, AmiPro, 
dBase, ASCII, others 

Windows and DOS Libraries $3,995 
Call for specs and demo. 
800-544-6339 

ZyLAB 

100 Lexington Drive • Buffalo Grove, IL 60089 
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32-bit Protected Mode 
386 C Graphics Library 

Intel 386/486 C Code Builder 
MetaWare, MicroWay, SVS, 
Watcom & Zortech with 
Phar Lap 3861 ASM 

Mixed Raster/Vector, 
Scalable, Rotatable Font, 
VGA, SVGA, 8514/A, VESA, 
Hercules Graphics Station 
through 1024x768x256 (8-bit), 
640x480x32k (16-bit), 
512x480x16.7m (32-bit), 
WYSIWYG HP-GL/PostScript 
$200 NO ROYALTIES 
FULL SOURCE CODE 
Gary R. Olhoeft 
P.O. Box 10870 Edgemont 
Golden, CO 80401-0620 
303-877-3697 CIS 76665,2021 
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Does your company provide 
tools, products, or services 
for advanced Windows 
programmers? 

Then reach over 27,000 
serious programmers in: 

Windows/DOS 

□ DEVELOPER'S JOURNAL 

Call 913-841-1G31 today for 
information about advertising 
opportunities in Windows/DOS 
Developer’s Journal. 

Advanced. Serious. 
Technical. 

Ed - East Donna - Midwast Edwin - West 


C and C++ DOCUMENTATION 


! AUTOMATED DOCUMENTATION ! 

• C-CALL ($69) Graphic-tree of caller/called 
functions, cross-ref, file/function index. 

• C-CMT ($69) Creates/inserts/updates 
comment-blocks for each function, listing 
the functions and identifiers used by it. 

• C-METRIC ($59)Counts path complexity, 
counts comments, code, ’C’ statements. 

• C-LIST ($69) Lists and action-diagrams, 
or reformats into standard formats. 

• C-REF ($59) Creates cross-reference of 
local/global/define/parameter identifiers. 

• SPECIAL : C-DOC ($199) All 5prqgrams 
integrated as DOS program (<15,000 lines) 

• NEW! C-DOC Professional ($299) 

DOS, OS/2, Windows. 3-ring binder/case. 
Processes 150,000 lines, deferred reports. 

• 30-DAY Money-back guarantee CALL NOW 

SOFTWARE BLACKSMITHS INC. 

6064 St Ives Way, Mississauga 

ONT, Canada Voice/Fax (4161-858-4466 

L5N-4M1 _Demos/BBS (41b)-85B-191b 


see AD INDEX for our larger ad 


VB Code without 

THE COMPROMISE 

If you're tired of 
having to choose 
between VB code 

VB Compress™ rewards 
good programming practice: 

Write code the way you should 

with plenty of white space, 

that is readable 

and EXEs that are 

comments, and descriptive names. 

the smallest and 

Manage code the way you want 

fastest they can be, 

with standard global files and 

then you need... 

libraries of standard routines. 

r VB „ 

Forget about that “code save/ 
code load” nonsense. 

Create VB EXE files that are 

Compress 

It lets you 
have it 

smaller and load faster without 
spending hours "optimizing" 
your code. 

Just $49.95 plus $5. s&h. 

For orders or information call: 

both 

TAILORED PCs 

ways! 

1-800-241-8727 
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First, it does not support ASSIGNed drives nor systems with 
three floppy drives. Second, it relies on changing information 
in the systems data areas — a practice that is highly incom¬ 
patible between different versions and sometimes has no ef¬ 
fect. 

There is a simple solution to all this. It’s the use of DOS 
IOCTL call 44H subfunction OFH. This function takes a drive 
number as a parameter and makes sure that the stated logi¬ 


cal drive is active for a physical drive with several logical iden¬ 
tifiers. There is no need for parameter range checking, be¬ 
cause DOS will automatically discern whether or not the 
parameter refers to a drive that needs to be adjusted. Before 
each file opens, the function activate_drive() (Listing 5) 
must be called with the same path that will be used with the 
open() call. □ 
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DON'T DEVELOP NETWORK APPLICATIONS 


without NPPC, a powerful library sub-routine package that 
handles all the details of NetBIOS or IPX programming! NPPC 
supports high-level program communications at the message 
level for all server/dient and peer-to-peer models. If you are 
using C or Assembler, NPPC allows you to write a single application 
that runs on BOTH IPX and NetBIOS without any modifications. 
NPPC is compatible with any true NetBIOS emulator, therefore, 
applications written with NPPC will work with most LANs in fee 
marketplace. We offer a 30 day money back guarantee! 

NPPC (IPX or NetBIOS): $195 With Source: $395 


LAN MODEM SERVER 


THE CONNECTION MANAGER - Low Cost 
system for sharing communications ports among 
LAN workstations. Controls number of modems, 
telephone lines, direct-connect ports, and other 
connection devices. Provides in-bound support, 
conference calling, multiple Servers (up to 16 
ports/Server). Topology independent Netware 
IPX/SPX or NetBIOS. Data rates to 115200 baud. 
Includes Full Feature LAN Communication software. 

The Connection Manager (IPX or NetBIOS): $395 

SOFTWAREHOUSE CORPORATION 

326 State Street, Los Altos, CA 94022 
415/949-0203 415/949-0208 (FAX) _ 
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Basie > C?f 


Basic is better than C when you 
use the ProBas library! Over 900 
routines, most in assembly, let you 
write fast, tight code without 
"C-headaches"! Easy to use, 30 
day money-back guarantee. For 
your FREE 20 page booklet call: 

800-447-9120 ext. 177 

TeraTech 

Dept. W177,3 Choke Cherry Rd., 

Ste. 360, Rockville MD 20850 
(301) 330-6764 Fax: 963-0436 
BBS: 963-7478 9600-N-8-1 

"A Supercharger for Basic" - BYTE 

New Visual Basic tools available! 

□ Request 101 on Reader Service Card □ 

Page 86 — Windows/DOS Developer’s Journal 



$79 DATA ACQUISITION FOR PCs 

■ 24 LINES OF PROGRAMMABLE DIGITAL INPUT/OUTPUT 

■ 3 CHANNEL 8 BIT A/D CONVERTER 

■ 12 BIT COUNTER 

■ PLUGS INTO PC BUS AND INCLUDES MANUAL AND 
FLOPPY 

$149 TRUE RMS DMM W/RS232 

■ MEASURES AC/DC VOLTS, CURRENT, OHMS, 
FREQUENCY 

■ OPTO-ISOLATED SERIAL PORT WITH CABLE FOR PC 

■ 20 AMP CURRENT RANGE, 30-40KHZ FREQUENCY 

■ INCLUDES CABLE AND DATA-LOGGING SOFTWARE 

$239 A/D CONVERTER W/RS232 

■ 18 BIT 5.5 DIGIT RESOLUTION (1 IN 200,000 COUNTS) 

■ ADDRESSABLE, CONNECT UP TO 32 ON 1 RS232 PORT 

■ VIRTUAL INSTRUMENT SOFTWARE & CABLE INCLUDED 


PRAIRIE DIGITAL INC. 

846 17TH STR INDUST PARK 
PRARIE DU SAC, WL 53576 


MAIL, FAX, OR PHONE 
VISA, MC, AX, CHECK, 
MO, OR PO ACCEPTED 


TEL 603-643-8598 INCLUDE $8 FOR S&H 

FAX 606-643-6754 
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Window List 


Click—"Click"—Invisible—Popup -Topmost - 
WindList Info—"WindList Info" -Invisible- 
WindList—"WindList"—Popup—Border—Dig 

BitView: Clipboard Data—"BitView"—Menu— 


Springtime Software 
1 - 800 - 458-2829 

81 Amherst Avenue, Waltham, MA 02154 
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- Batch compiles and links 

- Mainframe-type batch processing 

- Scheduled computing for LANS 

Queue jobs to run compiles, 
links, library updates on the 
fastest machine on your LAN. 

Cali now for trial version with 
30-day money back guarantee. 

■ KeyLogic 

PH 603.472.4006 FAX 603.472.2370 
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TUB " is FASTEST! 



RCS™ 4.2 PVCS'“ TLIB “ 3.0 TLIB'“ 5.0 


Times are to update a 45K library on a PC/XT. PVCS and TLIB 3.0 are 
from Sept 87 PC Tech Journal. MKS RCS 4.2 and TLIB 5.0 are newer, 

TLIB™ is BEST! 

"Do not be fooled by the fact that this is the 
least expensive of the five packages reviewed 
here - TLIB has features and power to spare" 
John Rex, Computer Language 
"TLIB is a great system" J. Vallino, PC Tech J 

• Full-Featured Version Control for Software 
Professionals. Check-in/out locking. Branching. 
Keywords. Wildcard and list-of-file support. Can 
merge parallel changes and undo intermediate 
revisions. Network and WORM support. Main¬ 
frame compatible deltas for Pansophic, ADR, IBM, 
etc.. Integrates with Opus'" MAKE & Slick " MAKE. 

MS-DOS $139, OS/2 $195 + shipping visa/MC 
5 station LAN license $419 (OS/2 $595), call for other sizes 

BURTON SYSTEMS SOFTWARE 

PO Box 4156, Cary, NC 27519 (919)233-8128 
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Fastgraph 

programmer’s graphics library 


Unlock the secrets of high- 
performance DOS graphics 
programming with the graphics 
library commercial games 
programmers have used for 
years. 

C • C++ • Pascal • BASIC • FORTRAN 

Only $169 

Call today for a free demo disk or download an 
evaluation kit from our BBS. No royalties. 
Visa, MC, COD, and purchase orders welcome. 

Ted Gruber Software 
PO Box 13408 Las Vegas, NV 89112 
Orders/Info (702) 735-1980 
FAX (702) 735-4603 • BBS (702) 796-7134 
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Windows 

Developer Jobs 


Specialists in jobs for software 
engineers in leading edge technology. 
Windows, PM, GUI, Languages, AI, 
Mac, CASE, Video, Realtime. 
Nationwide contacts with both large 
and small companies including equity 
startups. Many of our clients develop 
and publish commercial software 
products. Managed by graduate 
engineers. Never a fee to an 
applicant. 

1-800-231-5920 



Scientific Placement, Inc. 

SPI-8, Box 19949, Houston, TX 77224 (713) 496-6100 
SPI-8. Box 71, San Ramon, CA 94583 (510) 733-6168 
SPI-8. Box 4270, Johnson City, TN 37602 (615) 926-6188 
Fax: 713-496-6802 please use Fine Setting on Fax 
Email: Ascii preferred: Internet LSH@Scientific.com; 
^Q)mpuserve: 71250,3001; Genie: D.SMALL6 _ 1 
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Visual Basic, 
BASIC, and PDS 
programmers! 

fieneif Purpose Toolboxes 
grnpfiics 
Design 
Communicotions 


taer Printing 
Scientific Applications 
ISP's and more! 



Crescent Software offers mony tools for 
QuickBASIC, PDS, and Visual Basic. All 
products include complete source code, 
free technical support, and royalties are 
never required! (01 liUlWlI# i Ml DfMOMCUCfS 

CALL TOLL FREE 

1 800 35 BASIC 



CRESCENT SOFTWARE, INC. 

11 BAILEY AVENUE 
RIDGEFIELD. CT 06877-4505 
2034385300 FAX 2034314626 



Wilsoft carries a complete line of bar 
code software and hardware for your 
every need. All major barcode types 
supported. Call the most experienced 
company in the bar code field today. 
DOS and Xenix/Unix support. Por¬ 
table readers too! 

VISA/MC/AMEX/DISCOVER 

PO Box 6186 

Ft. Lauderdale, FL 33310-6186 
(305) 779-2720 
(305) 763-3096 Fax 
(800) 779-2720 Sales 
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UNIVERSAL 

Cross-Disassembler 


Missing source? Debugging? 
Upgrading an unsupported 
product? Then XDASM may be 
the solution. This unique MS- 
DOS based software disassembles 
programs for several types of 
microprocessors and 
microcontrollers. Creates an 
“Assembler Ready” source file 
from a Hex or Binary input file. Has configurable 
output to match assembler. Allows full control of 
disassembly using a separate TAG file. Assigns label 
names, provides instruction line detail, inserts 
assembler directives, deblocks source code into 
subroutines and generates multiple cross-reference lists. 
Processor families include: 1802, 4004, 6301. 65C02, 
6800, 6805, 6809, 68HCI I, 7810, 8048, 8051. 8085. 

8096, COP400 800, Z8, Z80, ZI80 plus others. Dual 
media diskettes and manual, $249. CROSS-16, the 
universal Meta-Assembler, available for $99. 

FREE Demo on BBS, 717-424-6754 (1200/2400, N,8,l) 
[ b| Data Sync Engineering 

■1 K P O. Box 146 
Ui East Stroudsburg. PA 18301 

Tel (717) 421-1977 Fax (717) 421-9095 
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Simtel20 MSDOS CDROM* $24.»5 

640 megabytes in 9000+ files. Programming tools. DOS 
utilities, tech docs, comm, bbs, publishing, ham-radio, 
education, and much more. Dated September 1992. 

CICA MS Windows CDROM* $24.95 

Hundreds of MS Windows programs. Utilities, games, 
source code, and programming tools. Dated July 1992. 

Source Code CDROM* $39.95 

X11R5 and GNU CDROM $39.95 

Info-Mac CDROM* $39.95 

GIFs Galore CDROM $24.95 

OS/2 Archive CDROM* $24.95 

AB20 Amiga CDROM* $24.95 

Garbo MSDOS/MAC CDROM* $24.95 
CDROM Caddies $4.95 

*Shareware programs require separate payment 
to authors if found useful. 

Walnut Creek CDROM 

*. 1547 Palos Verdes Mall 

Suite 260 
Walnut Creek, CA 94596 

+ 1-800-786-9907 

+ 1-510-947-5996 
FAX +1-510-947-1644 



Opt-Tech Sort/Merge 


Extremely fast Sort / Merge / 
Select utility. Run as an MS- 
DOS command or CALL as a 
subroutine. 

Supports most languages and 
filetypes including Btrieve and 
dBase. Unlimited filesizes, mul¬ 
tiple keys and much more! 

MS-DOS, Windows $149. 
OS/2, UNIX $249. 


Opt-Tech Data Processing 

£ P. O. Box 678 
Zephyr Cove. NV 89448 

(702) 588-3737 
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Discover why FoxPro, Clipper, 
and dBASE were all written in C. 


#here is a good reason why 
• your database language was 
developed in C. In fact, there 
are many good reasons. 

C code is small. C code is fast. C code is 
portable. C code is flexible. C is the 
language of choice for today's professional 
developer. With the growing complexity of 
database applications, C is a realistic 
alternative. Now with CodeBase 5.0, you 
can have all the functionality, simplicity and 
power of traditional database languages 
together with the benefits of C/C++. 

C speed - fast code, true executables... 

FoxPro, Clipper, and dBASE were written 
in C primarily for speed. But those compilers 
don't really compile, they combine imbedded 
language interpreters into your .EXE. Now 
that's slow. For dazzling performance you 
need the true executables of C. With 
CodeBase you get the real thing, C code. 
Consider the following statistics, from the 
publisher of Clipper: 



"Sieve of Erastothenes" 

Benchmark for Prime Number Generation 
Shows C to be incredibly faster! 

C size ■ small executables, 
no added overhead... 

FoxPro, Clipper and dBASE would like you 
to believe you need their entire development 
system to build database applications. But 


remember, those products are all written in 
C. So why do you need to lug all their extra 
code around? You don't. CodeBase is a 
complete DBMS, in C. No fat executables 
stuffed with unused code. No runtime 
modules. No royalties. Just quality C code. 
CodeBase is just what you need. 


data files with any logical dBASE expression. 
Our new Bit Optimization Technology 
(similar to FoxPro’s Rushmore technology) 
uses index files to return a query on a 1/2 
million record data file in just a second. 
Automatically take advantage of this query 
performance by using our new CodeReporter: 


C portability ■ ANSI C/C++ 
on every hardware platform... 

No other language exists on more platforms 
than C/C++. Why rewrite your entire 
application for DOS, Windows, Windows 
NT, OS/2 or UNIX? With CodeBase the 
complete C source code is included, so you 
can port to any platform with an ANSI C or 
C++ compiler. Now and in the future. 

dBASE Compatible data, index 
and memo fifes... 

You want the industry standard. You need 
compatibility. Sure, dBASE is the standard, 
but every dBASE compatible DBMS 
product uses its own unique index and memo 
file formats. Only CodeBase has them all: 
FoxPro (.cdx), Clipper (.ntx), dBASE IV 
(.mdx) and dBASE III (.ndx). Now it's your 
choice, we're compatible with you. 

Announcing 
CodeBase 51) 

The power of a complete DBMS , the benefits of C 

NEW - Multi-user sharing with 
FoxPro, Clipper and dBASE... 

Now your multi-user C/C++ programs can 
share data, index and memo files at the 
same time as concurrently running FoxPro, 
Clipper and dBASE programs. No 
incompatibilities. No waiting. 

NEW - Queries & Relations 
1000 times faster... 

CodeBase 5.0 now lets you query related 


E>le Aligt^BatabB8^GroupsG|obaiPrint'QuerySty!e^de!^^^^^^^^^^'|| 

Title: Objects: 1: Height: 36.0 Points 


Product Sales Sumn 

Product Sales Summary 

Month ot: Nov. 1992 

Product Quantity Value 

Database 63 125.137 00 

Spreadsheet 58 <21.866 00 

Monthly Summary 121 S47.003.00 

Month; Header; Objects: 5; Height 48.0 Points 

Montk of! BKTUHI 

Producl jQuantityd |VaM 

Body; Header: Objects: 3; Height: 14.0 Points 

w UNE-.PRMUCTI IM IW liJ 

Month: Footer; Objects: 4; Height: 48.0 Points 

Month oC Dec. 1992 

Product Quantity Value 

Database 62 <24.86200 

Spread Sheet 53 <19.875.00 

Monthly Summary 115 344.737.00 

IMonthiy Symm^ M+OTALj_fejOOLLA_ 


Summary; Ob|ects: 3; Height: 36.0 Points 

ISummd ifdTAL' I COLLAR! 




Summary 236 S91.740.00 

To use CodeReporter, 



simply draw your report, then include it in any 
program you write. Call 403/437-2410 now for 
your FREE working model of CodeReporter. 

New - Design complex reports 
in just minutes... 

Our new CodeReporter takes the painstaking 
work out of reports. Now simply design and 
draw reports interactively under Windows 3.1, 
then print or display them from any DOS, 
Windows or UNIX application. 

SPECIAL - FREE CodeReporter 

Order CodeBase 5 before Feb. 28, 1993 and 
receive CodeReporter for free! This offer 
includes our no-risk, 90-day money back 
guarantee, so order today! 



CocteSose 5.0 

The C/C++ Library for DataBase Management 

Call Now 
403 - 437-2410 


SEQUITER 

SOFTWARE INC. 


FAX 

Europe 


403*436*2999 

33.20.24.20.14 


#209,9644-54 AVE.. EDMONTON. AB. CANADA T6E-5V1 


01992 Sequitcr Software Inc. All rights reserved. CodeBase is a trademark ol'Sequiter Software Inc. All other trade names referenced herein are property of their respective companies. MAdvertising by MicroArts 
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Welcome to the age of 
automated memory/heap protection! 

NEW BOUNDS-CHECKER 2.0 is the only complete solution to MS-DOS 
memory smd heap corruption problems. 

BOUND-CHECKER 2,0 is a single, easy to use utility that automatically 
detects problems in your programs heap, stack or data segment and 
finds illegal memory accesses outside of your program or in your code, 
In or)e step, you can quickly and easily flush out some of the most 
insidious bugs that you regularly encounter as a DOS programmer. 


• New 2.0 Features • 

Now works with 3rd party memory managers 

Heap, stack and data segment checking 

Smart Mode decides the legitimacy of an access automatically 

No need to see assembly code - call stack lets you view source 

of calling routines. 

New Auto Log mode (BC doesn't pop up) 

Supports C7.0 & Borland 3.1 & VROOM 

Order NOW! Only $199 


Using BOUNDS-CHECKER 2.0 is simple, there are no changes to be made 
to your source in any way, and no linking of code or macros into your 
executable. When a bug is found, BOUNDS-CHECKER pops up showing 
you precisely where the problern is. 

One of its innovative NEW features is Smart Mode. Smart Mode uses a 
built-in knowledge base to automatically determine if an out-of-bounds 
access is legitimate. This eliminates any complex decisions on your part, 
resulting in more power and flexibility than you may have thought 
possible. 

Don't take unnecessary risks with your program or your customers, 
BOUNDS-CHECK before you ship with NEW version 2,0. 


For even more debugging power, BOUNDS-CHECKER 2.0 
integrates with our award-winning Soft-ICE debugger which fea¬ 
tures powerful 386/486 based breakpoints. Equipped with this 
formidable combination, your de-bugging arsenal is prepared for 
any surprise attack of the DOS Nasties. 

Soft-ICE...$386 

BOUNDS-CHECKER 2.0 & Soft-ICE Bundle Only...$499 

BOUNDS-CHECKER AND SOFT-ICE ARE TRADEMARKS OF NU-MEGA TECHNOLOGIES, INC. 


We're making C a Safe Language! 


Cali (603) 889-2386 
fax (603) 889-1135 

Sf 1 

N 

b-] 

VI 

tea 

RISK = NULL 

30 DAY 

MONEY-BACK GUARANTEE 

P.O. Box 7780 

Nashua, NH 03060-7780 U.S.A. 

^TECHNOLOGIES INC 

24 HOUR BBS 
603-595-0386 
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